# 🦀 rflow 🦀

> rflow is a blazing-fast onchain workflow engine written in Rust — one rflow.yaml maps triggers to chains of actions with exactly-once execution

## Approvals — human-in-the-loop sends

Some transactions should not fire without a human saying so — big treasury
moves, emergency responses, anything above a threshold. `approval:` on a
[`send_transaction`](/workflows/steps/send-transaction) step parks the run with
the transaction **fully prepared and simulated**, notifies the approvers, and
only broadcasts after an explicit yes.

```yaml
workflows:
  treasury-sweep:
    trigger:
      cron: { expression: "0 9 * * 1" }
    steps:
      - id: sweep
        send_transaction:
          network: ethereum
          relayer: treasury
          contract: USDC
          function: "transfer(address,uint256)"
          args: ["${{ constants.cold_storage }}", "${{ steps.balance.output }}"]
          approval:
            via: [telegram: ops, cli]
            timeout: 4h
            on_timeout: fail        # fail (default) | proceed (warned)
            message: "sweeping ${{ format_units(steps.balance.output, 6) }} USDC to cold storage"
          recheck: "${{ steps.balance.output > wei('1000', 6) }}"
```

### The approval block

| Field        | Default    | Description                                                                                                       |
| ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `via`        | ✅ required | Approval routes, non-empty: `telegram: <channel>` (a [notifications channel](/config/notifications)) and/or `cli` |
| `timeout`    |            | How long to wait for a decision, e.g. `1h`                                                                        |
| `on_timeout` | `fail`     | What an undecided timeout does: `fail` \| `proceed`                                                               |
| `message`    |            | Template shown to the approver — the decoded call + simulation result are always included                         |

### Approval policies — N-of-M quorums

For two-person review, name the people and the quorum instead of a route
list. **Approvers are identity objects**: each route maps a channel to the
member's address, and the address doubles as the attribution key. Channels
keep holding credentials (`via_channel` points at a
[notifications channel](/config/notifications)); approvers hold addresses.

```yaml
approvers:
  alice:
    cli: { token: ops-alice }                          # named api token (rflow token create)
    telegram: { chat_id: "12345678", via_channel: ops } # her PRIVATE chat with the bot
  bob:
    sms: { to: "+447700900123", via_channel: ops-sms }  # over the twilio channel's account
  carol:
    cli: { token: ops-carol }

approver_groups:
  ops: [alice, bob, carol]

approval_policies:
  two-of-ops:
    group: ops
    required: 2          # validated: 1 <= required <= group size (groups max 25)
    timeout: 4h          # hard 30-day ceiling; absent = wait the full ceiling
    remind_every: 1h     # re-notify undecided members (journaled)
    on_timeout: fail     # NEVER manufactures a decision; `proceed` is warned
    on_reject: fail      # first rejection VETOES (default); `wait` = fail only
                         # once `required` approvals become impossible
    escalate: ops        # notify-only when the quorum expires undecided
```

Reference it from the send — a bare policy, or **amount tiers** (ordered,
first `when:` match wins, a trailing no-`when` tier is the default, no match
\= no gate; `value` is the prepared send's native value in wei):

```yaml
          approval:
            policy: two-of-ops
# or
          approval:
            - when: "${{ value > wei('50', 18) }}"
              policy: two-of-ops
            - policy: one-of-ops
```

Semantics that make the quorum safe:

* **The snapshot is pinned at park time.** Members, `required`, timeouts and
  routes are frozen onto the approval row — a later config edit never
  changes a pending quorum.
* **One member counts once.** Decisions are journaled per member with a
  unique key; a duplicate command, replayed link, or the same person on two
  channels cannot double-count.
* **Members with a `telegram:`/`sms:` route get their own private notice**
  (CLI-only members decide from `rflow approvals ls` with their token) — a
  DM / SMS over the channel's credential, carrying a **signed one-time
  approval link**
  (when `config.server.public_url` is set) plus the CLI one-liners. The link
  is a bearer credential bound to one member of one approval: single-use,
  expires with the quorum, GET only renders the confirm page (scanners
  cannot spend it), the decision is a POST.
* **CLI decisions must prove membership**: `rflow approve <id> --token <api-token>` (or `RFLOW_API_TOKEN`) — the token's *name* maps to
  `approvers.<member>.cli.token`. `cli:$USER` is never accepted for quorums.
* **Everything is journaled**: per-member decisions (member, route, reason,
  time) in `rflow.approval_decisions`, an `operator_audit` row per decision,
  and the full trail in `rflow runs show` / `GET /api/runs/{id}`. Retention
  keeps everything by default; when an operator-configured window prunes a
  decided approval (or its whole run), the decision/link rows cascade away
  with it — the `operator_audit` trail survives pruning by design.

### Safe proposal mode

`send_transaction.propose_to_safe:` PROPOSES the prepared tx to a
[Safe](https://safe.global) via the Safe Transaction Service instead of
broadcasting — the Safe's own owner threshold then governs execution in
Safe\{Wallet}. An integration, not custody: rflow holds a revocable
**delegate** key that can only propose, never execute.

```yaml
        send_transaction:
          network: ethereum
          relayer: treasury          # unused in this mode (no broadcast)
          contract: USDC
          function: "transfer(address,uint256)"
          args: ["${{ constants.cold_storage }}", "${{ steps.balance.output }}"]
          approval:
            policy: two-of-ops       # rflow's gate = proposal hygiene
          propose_to_safe:
            safe: "0xYourSafe..."
            delegate_key: ${SAFE_DELEGATE_KEY}
            service_url: https://api.safe.global/tx-service/eth
            api_key: ${SAFE_API_KEY}   # optional; anonymous is rate-limited
```

Every gate still runs first (permissions, simulation, gas caps, recheck,
rflow approval); the step then signs the `safeTxHash` (v1.3.0+ domain) with
the delegate key and posts the proposal — output carries `safe_tx_hash` and
the nonce. Register the delegate once with the service (an owner signs the
Delegate message). Know the edges: a proposal **cannot be un-proposed** (an
rflow approval timeout upstream simply means nothing is proposed), and the
Safe queue is nonce-ordered — concurrent proposers race for the next nonce.

### The lifecycle

1. **Prior steps have already run.** The gate is on *this transaction*, not the
   workflow — reads, HTTP enrichment and guard steps complete first, so the
   approver sees final values.
2. **The transaction is prepared and simulated.** Simulation,
   [`assert_sim`](/workflows/steps/send-transaction#assert_sim--gates-over-the-simulation)
   and gas caps all run *before* anyone is asked — a send that would revert
   never bothers a human.
3. **The run parks durably** (`waiting_approval`): the approval row
   (`rflow.approvals`), its expiry and the prepared tx summary are journaled in
   the same transaction that parks the step. A crash or restart while parked
   loses nothing; a recovering executor adopts the pending row.
4. **Approvers are notified** through every `via:` route — the notice carries
   the workflow, run and step ids, your `message`, the decoded call summary and
   the exact `rflow approve`/`reject` one-liners. Notification failures are
   logged, never fatal: the gate is the database row, so the CLI always works
   even when every channel is down.
5. **A decision settles it** — decisions are single-shot (`WHERE status =
   'pending'`), so a double-approve or a race against the expiry poll changes
   nothing and reports what actually happened.

| Decision     | Effect                                                                                                                                                                                                                                                                |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **approved** | The send **re-runs [`recheck:`](/workflows/steps/send-transaction#recheck--dont-fire-stale) and re-simulates** against current state, then broadcasts under the same idempotency key. Conditions moved while the human decided → the send is dropped, not fired stale |
| **rejected** | The step fails (kind `dropped`, the reason journaled); [`on_failure`](/workflows#failure-handling) applies                                                                                                                                                            |
| **expired**  | `on_timeout` decides: `fail` — the step fails with kind `expired`, nothing broadcasts. `proceed` — see below                                                                                                                                                          |

### Deciding: CLI

```bash
rflow approvals ls              # pending approvals (--all includes decided/expired)
rflow approve <id> [--yes]      # <id> is the approval id or the run id
rflow reject <id> --reason "gas too high today"
```

`rflow approve` prints the prepared transaction and asks for confirmation
(`--yes` skips it). Since steps are strictly sequential, a run has at most one
pending approval — the run id works as the `<id>`. Pending approvals are also
visible in `rflow runs show <run>` and the [run-trace viewer](/observability).

An AI agent operating the project via [MCP](/mcp) can *see* pending approvals
in the journal but has no approve/reject tool — deciding a money gate stays
with humans and the CLI, deliberately.

### on\_timeout: proceed — the sharp edge

:::warning
`on_timeout: proceed` treats an unanswered gate as **consent**: when the
timeout elapses undecided, the send rechecks, re-simulates and **broadcasts
with nobody having approved it**. `rflow validate` warns about every step that
sets it. Use it only where an unanswered gate must never block (and pair it
with a tight `recheck:`); everywhere else the default `fail` is the honest
choice.
:::

### Semantics worth knowing

* **Webhook callers see 429** while their workflow's run is parked at a gate —
  the caller's retry loop redelivers naturally once the run settles.
* **Dry-run sessions auto-proceed**: in [`rflow replay` / `rflow test`](/backtesting)
  the gate does not park — the journal carries an `approval.required` marker so
  you still see *where* a human would have been asked.
* **`on_reorg:` steps may not contain approval gates** (validated) — reorg
  responses must stay fast and unattended.
* The pagerduty/opsgenie channels classify approval requests as `info`/`P5` —
  a request for a decision, not an incident.


## Backtesting — replay, test & dry-run

Would your workflow have done the right thing? `rflow replay` answers with
**real historical blocks**: it re-indexes a range, fires your trigger exactly
as live would, runs every step in dry-run mode — simulation, gas caps, policy
checks, `assert_sim`, `recheck` all included — and reports what it *would have
sent*. `rflow test` is the single-shot sibling for one fixture or one real
transaction — for **every** trigger kind. Nothing broadcasts unless you
explicitly go `--live`.

No hosted automation platform lets you do this. Your YAML is testable against
the chain's actual history before a single wei moves.

At a glance:

| Command                                                                                   | What it does                                                                |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `rflow replay <wf> --from-block A [--to-block B]`                                         | Replay a range through an **event- or block-triggered** workflow (dry-run)  |
| `rflow replay <wf> … --with-waits waits.json`                                             | Resolve `wait_for:` saga steps deterministically for the rehearsal          |
| `rflow replay <wf> … --diff OTHER_DIR`                                                    | Diff the same range against another project version — did behaviour change? |
| `rflow replay <wf> … --output json\|junit`                                                | Emit a CI-friendly report (exit non-zero on failure)                        |
| `rflow replay ls`                                                                         | List every replay/test session                                              |
| `rflow replay prune --older-than 7d \| --session ID \| --all`                             | Delete sessions (rows, indexer schemas, runtime dirs)                       |
| `rflow test <wf> --fixture f.json` (or `--event`/`--from-tx`/`--cron-at`/`--read-output`) | One dry-run from a fixture, for any trigger kind                            |

### rflow replay — a range of history

```bash
rflow replay <workflow> --from-block <n> [--to-block <n>] [--timeout <secs>] [--live] [--yes]
```

Replay drives **event** triggers (via a bounded re-index of the range) and
**block** triggers (one dry-run per block where `block % every == 0`, deduped by
block number). Cron/webhook/read/query workflows have no block-bounded history
to replay from — use [`rflow test`](#rflow-test--one-run-from-a-fixture) with a
fixture for those.

Every output below is a real session from the repo's
[`token-transfer-relay` example](/getting-started/examples): three historical
deposits landed on the local chain (250, 25 and 500 RFT — the workflow's
`where:` only matches deposits ≥ 100), then:

```bash
rflow replay echo-deposit --from-block 40 --to-block 46
```

```
dry-run replay of 'echo-deposit' from block 40 to 46 - nothing will be sent

replay 20260724034558fe323d - 'echo-deposit' blocks 40..=46 on local_anvil (dry-run)
 block | tx                 | run       | steps | would send
 43    | 0xfe24bb08da25fb6… | succeeded | 2 ok  | transfer(address,uint256) -> 0x5FbDB231567…, gas 51710
 45    | 0x75a03bb563b6a7c… | succeeded | 2 ok  | transfer(address,uint256) -> 0x5FbDB231567…, gas 51710

2 event(s) matched, 2 run(s), 2 would-be send(s)
session journal: rflow runs list (workflow 'replay_20260724034558fe323d__echo-deposit') - live history untouched
```

The 25 RFT deposit at block 44 is correctly absent — the `where:` filtered it,
exactly as live would. Each row is one claimed run: the triggering event, the
per-step outcomes (`2 ok` / `failed at <step>`), and the decoded would-be send
with its simulated gas.

#### What dry-run means, precisely

Every check that can run without side effects **still runs**: templates,
permissions, relayer policy caps, simulation, `assert_sim`, gas caps,
`recheck`. But nothing leaves the process:

| Action                                   | Dry-run behaviour                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `send_transaction`                       | Stops right before the relayer hand-off; reports the `would_send` summary + simulation result                                                                                                                                                                                                                                     |
| `http_call` / `notify`                   | The prepared request is logged, never fired                                                                                                                                                                                                                                                                                       |
| [`command`](/workflows/steps/command)    | **Executes for real by default** (`dry_run: execute`) — a command may be needed to produce the would-be tx params a later step rehearses. rflow cannot know what arbitrary local code does (files, external APIs), so set `dry_run: skip` on any command with side effects to short-circuit it with `{ "skipped": true }` instead |
| `delay`                                  | Shrinks to zero (logged)                                                                                                                                                                                                                                                                                                          |
| `approval:`                              | Auto-proceeds; the journal carries an `approval.required` marker where a human would have been asked                                                                                                                                                                                                                              |
| `state_set` / `list_add` / `list_remove` | Writes are skipped; `would_set` / `would_mutate` journaled instead                                                                                                                                                                                                                                                                |
| `wait_for`                               | Settles immediately with a `would_wait_for` output — unless you pin the outcome with [`--with-waits`](#saga-rehearsals----with-waits)                                                                                                                                                                                             |

#### The isolation model

A replay boots an **isolated session**: a bounded indexer manifest for just
this workflow and range, registered under a namespaced name
(`replay_<session>__<workflow>`) with a `replay:<session>:` trigger-key prefix.
Consequences, all deliberate:

* **live dedupe is untouched** — a live claim and a replay claim of the same
  event coexist
* a live `rflow start` never picks up replay runs, and the replay executor
  never picks up live runs
* the workflow's own run history stays clean — replay runs journal under the
  namespaced name
* `trigger.throttle` is dropped for the session (a rehearsal must not consume
  the live throttle window — replay shows *every* match), the trigger is
  forced to confirmed-at-depth-0 (historical blocks are final), and decoded
  fires are never offered to live parked [`wait_for` sagas](/workflows/steps/wait-for)
* `paused:` is ignored — replaying a paused workflow is an explicit operator
  action

#### Block-trigger replay

A [block trigger](/workflows/triggers/block) (`block: { every: N }`) has no
event stream — replay instead fires **one dry-run per block** in `[A, B]` where
`block % every == 0`, deduped by block number, building `trigger.args = { block_number, network }` for each. It needs no chain access when you pass an
explicit `--to-block` (the block numbers are computed, not fetched):

```bash
rflow replay every-fifth-block --from-block 100 --to-block 120
```

```
replay 20260802213528773ba1 - 'every-fifth-block' blocks 100..=120 on local (dry-run)
 block | tx | run       | steps | would send
 100   | -  | succeeded | 1 ok  | ...
 105   | -  | succeeded | 1 ok  | ...
 110   | -  | succeeded | 1 ok  | ...
 115   | -  | succeeded | 1 ok  | ...
 120   | -  | succeeded | 1 ok  | ...

5 event(s) matched, 5 run(s), 0 would-be send(s)
```

#### Listing & pruning sessions — `rflow replay ls` / `prune`

Replay and test sessions **leave their journal behind** — namespaced rows in
`rflow.workflows` / `rflow.workflow_runs`, a per-session rindexer schema (event
replays), and a `.rflow/runtime/replay-<id>/` directory. `rflow replay ls`
shows them all:

```bash
rflow replay ls
```

```
 session              | workflow          | kind   | created             | runs | runtime dir
 20260802213528773ba1 | every-fifth-block | replay | 2026-08-02 21:35:28 | 5    | yes
 ac03575f             | settle-saga       | test   | 2026-08-02 21:34:45 | 3    | -
```

`rflow replay prune` deletes them — namespaced journal rows (one guarded
transaction), the rindexer schema (`DROP SCHEMA … CASCADE`) and the runtime
directory. It requires a selector so a bare `prune` can never nuke everything,
and it **only ever touches namespaced sessions** — a live workflow, its runs and
its analytics schema are never deleted:

```bash
rflow replay prune --older-than 7d      # sessions created > 7d ago
rflow replay prune --session <id>       # one session by id
rflow replay prune --all                # every replay/test session
```

```
pruned 6 session(s) - live workflows and their runs were not touched
```

The `replay_<id>__<name>` / `test_<id>__<name>` naming pattern is **reserved
for sessions**: `rflow validate` rejects a live workflow named into it, and —
belt-and-braces for journals created before that rule — `prune` cross-checks
every discovered session against the workflows declared in `rflow.yaml` and
refuses to touch a name that is a live config workflow.

#### Two requirements to know about

:::warning
* **Event & block triggers only.** Cron/webhook/read/query workflows have no
  historical block-bounded stream to replay — use `rflow test` for those (the
  error message says the same).
* **Relayer references need persisted mappings.** Dry-run resolves
  `relayers.<name>.address` from the `rflow.relayers` mappings, so a project
  that never booted live errors on steps referencing them. One
  `rflow relayers sync` (no funds needed) creates the mappings.
:::

#### --live — replay with real money

`--live` boots the relayer engine and **sends real transactions** for every
historical match that passes its checks. It takes the project lock (a running
`rflow start` shares wallets and nonces) and makes you type `send` — not `y` —
at a red prompt:

```
!!! LIVE REPLAY !!!
every historical 'echo-deposit' event in blocks 40..=46 that passes its checks will
SEND A REAL TRANSACTION through your relayers.
this is NOT a rehearsal - money moves.
type 'send' to proceed (anything else aborts):
```

Use it for deliberate historical catch-up ("process everything I missed last
week, for real"), not for testing.

### rflow test — one run from a fixture

```bash
rflow test <workflow> --fixture <fixture.json>  # trigger payload for the workflow's OWN kind
rflow test <workflow> --event <fixture.json>    # event fixture (event workflows)
rflow test <workflow> --from-tx <tx-hash>       # trigger decoded from a real receipt
rflow test <workflow> --cron-at <ISO8601>       # cron workflows
rflow test <workflow> --read-output <out.json>  # read/query workflows
```

No indexer at all: one run is claimed under a namespaced name and driven to a
terminal state in dry-run mode. `--from-tx` fetches the receipt and decodes the
log that matches your trigger — the fastest way to ask *"what would this
workflow have done with that transaction?"*:

```bash
rflow test echo-deposit --from-tx 0xfe24bb08da25fb6403d9d2348a30703686d25a015e64c0bfa5763dd3ac98aa1c
```

```
dry-run of 'echo-deposit' - nothing will be sent

test ea233669f4c445d88fefa2978fe5ec12 - 'echo-deposit' (dry-run, trigger tx 0xfe24bb08da25fb6…)
 step        | action           | outcome   | detail
 gate (#1)   | read             | succeeded | "1000000000000000000000000"
 payout (#1) | send_transaction | succeeded | would send transfer(address,uint256) -> 0x5FbDB2315678afecb367f032d93F642f6…

test run succeeded (2 step rows journaled under 'test_ea233669__echo-deposit')
```

#### A fixture for every trigger kind — `--fixture`

`--fixture <file>` interprets the file against the **workflow's own trigger
kind** and builds the exact `trigger.*` roots a live fire would have journaled.
A fixture whose shape does not match the kind (a webhook body against an event
workflow) errors clearly. Each kind's shape:

| Trigger   | Fixture shape                                                 | Builds                                                                         |
| --------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `event`   | `{ "args": {…}, "tx_hash"?, "block_number"?, "network"?, … }` | `trigger.args` + the event envelope (defaults filled from the trigger)         |
| `cron`    | `{ "scheduled_for": "2026-08-02T09:00:00Z" }`                 | `trigger.scheduled_for`, `trigger.workflow`                                    |
| `webhook` | `{ "body": {…}, "headers"?: {…} }`                            | `trigger.args` = body, `trigger.webhook.{path, received_at, headers?}`         |
| `read`    | `{ "output": <decoded read result> }`                         | `trigger.args.{output,value}`, `trigger.read.{function, network, observed_at}` |
| `query`   | `{ "output": <shaped query output> }`                         | `trigger.args.output`, `trigger.query.observed_at`                             |
| `block`   | `{ "block_number": 19000000, "network"?: "…" }`               | `trigger.args.{block_number, network}`                                         |

```bash
rflow test deposit-hook --fixture webhook.json     # { "body": { "amount": "500" } }
rflow test every-fifth-block --fixture block.json  # { "block_number": 19000005 }
```

```
test 35d0890757294e008352ee15469b87bf - 'deposit-hook' (webhook dry-run)
 step            | action    | outcome   | detail
 log_amount (#1) | state_set | succeeded | would set state.webhook_amount = 500
```

Two convenience flags are sugar over `--fixture`:

```bash
rflow test nightly-report --cron-at 2026-08-02T09:00:00Z   # cron workflows
rflow test utilization-guard --read-output util.json       # read/query workflows: { "output": "…" }
```

`--event` is the event-only alias (`{"args": {...}}` plus optional envelope
fields) kept for backwards compatibility; `--fixture` supersedes it for event
workflows too.

Reads and simulations run against the network's **current** state (an
`eth_call` cannot time-travel on a normal RPC) — for state-at-height fidelity,
point the network's `rpc:` at an archive fork (e.g.
`anvil --fork-url $ETH_RPC --fork-block-number <n>`) via a
[profile](/config/profiles). Read/query replay uses the `--read-output` you
supply, not reconstructed archive state — see
[non-goals](#non-goals).

### Saga rehearsals — `--with-waits`

A [`wait_for:` saga](/workflows/steps/wait-for) parks the run until a matching
event or a timeout. In a rehearsal there is no live event to wait for, so by
default the wait settles immediately (`would_wait_for`). `--with-waits <file>`
pins each wait step's outcome **deterministically** so you can rehearse both
branches — available on `rflow test` **and** `rflow replay`:

```json [waits.json]
{
  "await_settle": { "event": { "args": { "id": "1", "payout": "990" } } }
}
```

```bash
rflow test settle-saga --fixture deposit.json --with-waits waits.json
```

The matched event becomes the wait step's output, so downstream steps run and
can read `steps.await_settle.output.*`:

```
 step              | action    | outcome   | detail
 kickoff (#1)      | state_set | succeeded | would set state.saga_started = 1
 await_settle (#1) | wait_for  | succeeded | {"args":{"id":"1","payout":"990"}}
 finalize (#1)     | state_set | succeeded | would set state.saga_settled = 1
```

Swap the outcome to `{ "await_settle": { "timeout": true } }` and the wait takes
its `on_timeout` path (`fail` | `continue` | `goto`) — here `on_timeout: fail`
dead-letters the run (and the process exits non-zero), exercising the timeout
branch:

```
 await_settle (#1) | wait_for  | failed    | timeout: wait_for timed out (fixture) before any condition matched
```

Wait steps not named in the file fall back to the default immediate settle.
Fixtures key on the **config** step id: waits inside a `foreach` (`fan[0]`,
`fan[1]`, ...) or a `finally:` block all resolve through their base id, so one
`"fan": {...}` entry pins every item's outcome.

### Version diff — `--diff`

Did your change alter behaviour over real history? `--diff OTHER_PROJECT_DIR`
replays the **same range/fixtures** against both the current project and
another project's same-named workflow (both dry-run, isolated sessions), then
prints the per-trigger delta — added / removed / changed would-sends and status
changes:

```bash
rflow replay every-fifth-block --from-block 100 --to-block 120 --diff ../old-version
```

```
diff 'every-fifth-block' blocks 100..=120 - this project vs the other project
 trigger         | change    | before (this project) | after (other project)
 block:local:100 | unchanged | succeeded [no sends]  | succeeded [no sends]
 block:local:105 | removed   | succeeded [no sends]  | (did not fire)
 block:local:110 | unchanged | succeeded [no sends]  | succeeded [no sends]

5 matched, 0 changed, 0 added, 2 removed, 3 unchanged - behaviour DIFFERS over this history
```

The command **exits non-zero** when behaviour differs, so a diff can gate a PR.
If the other project is missing the workflow or declares a different trigger
kind, it errors. The diff compares dry-run *decisions* (status + would-send
params, including the exact calldata — an args-only or multicall inner-call
change counts as changed), not live outcomes.

### CI output — `--output json | junit`

Both `rflow test` and `rflow replay` take `--output human` (default), `json` or
`junit`. `rflow test` exits non-zero when any run failed, so a fixture doubles
as a CI check; `json`/`junit` still print.

`--output json` emits one structured object (`{ session, workflow,
trigger_kind, runs: [ { trigger_key, status, steps } ], summary }`). `--output
junit` emits a `<testsuite>` with one `<testcase>` per run (failed / dead-lettered
runs carry a `<failure>`) that GitHub Actions and GitLab render natively:

```yaml [.github/workflows/backtest.yml]
name: backtest
on: [pull_request]
jobs:
  fixtures:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_PASSWORD: rflow }
        ports: ["5432:5432"]
    env:
      DATABASE_URL: postgresql://postgres:rflow@localhost:5432/postgres
    steps:
      - uses: actions/checkout@v4
      - run: cargo install --git https://github.com/joshstevens19/rflow rflow_cli
      - name: rehearse the settle saga (both branches)
        run: |
          rflow test settle-saga --fixture fixtures/deposit.json \
            --with-waits fixtures/waits-event.json --output junit > settle.xml
      - name: publish results
        if: always()
        uses: mikepenz/action-junit-report@v4
        with:
          report_paths: "*.xml"
```

### Non-goals

* **No perfect historical off-chain reconstruction.** Read/query replay uses
  the `--read-output` value you supply (or, for real fork state, point `rpc:` at
  an archive fork via [`rflow dev --fork`](/config/profiles)); rflow does not
  reconstruct historical off-chain API responses.
* **No hosted simulation cluster.** Replay runs locally against your Postgres.
* **Not a Foundry replacement.** rflow rehearses *workflow decisions*, not
  contract internals — keep your Solidity tests.

### Where this fits

| I want to...                                         | Use                                                                                                                |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Check the YAML parses and references resolve         | `rflow validate` (+ [`--preflight`](/observability#preflight-checks--rflow-validate---preflight) for connectivity) |
| See what one event/transaction would do              | `rflow test --from-tx` / `--event`                                                                                 |
| Rehearse a cron / webhook / read / block workflow    | `rflow test --fixture` / `--cron-at` / `--read-output`                                                             |
| Rehearse a saga's matched **and** timeout branch     | `rflow test … --with-waits`                                                                                        |
| Backtest a filter or strategy over real history      | `rflow replay --from-block ... --to-block ...`                                                                     |
| Check my change did not alter behaviour over history | `rflow replay … --diff OTHER_DIR`                                                                                  |
| Gate a PR on fixtures in CI                          | `rflow test … --output junit` (non-zero exit on failure)                                                           |
| Clean up replay/test sessions                        | `rflow replay ls` then `rflow replay prune`                                                                        |
| Process missed history **for real**                  | `rflow replay --live` (typed confirmation)                                                                         |
| Watch it work end-to-end locally                     | the [runnable examples](/getting-started/examples)                                                                 |


## Benchmarks

rflow's performance claim is architectural: event decode → expression eval →
relayer hand-off are **in-process function calls** — no HTTP hop, no
serialization on the hot path. This page puts numbers on that, and is precise
about what was measured and what was not.

### Headline numbers

The engine-side hot path — **event claimed → transaction queued in the embedded
relayer** — measured over 30 event-triggered sends:

| Metric                                                                         | p50         | p95     | max     |
| ------------------------------------------------------------------------------ | ----------- | ------- | ------- |
| Claim → tx queued (simulate + estimate gas + policy checks + relayer hand-off) | **25.1 ms** | 34.3 ms | 39.2 ms |
| Claim → run settled (full run, single send step, `wait_for: none`)             | 28.1 ms     | 37.3 ms | —       |
| Event's block timestamp → claim (detection, polling a 1s-block chain)          | 0.83 s      | 0.91 s  | 0.92 s  |

Those \~25 ms include real work, all of it journaled: the exactly-once claim
transaction in Postgres, template evaluation, a pre-flight `eth_call`
simulation, an `eth_estimateGas`, policy/gas-cap checks, the pre-send journal
write with the idempotency key, and the in-process relayer queue insert.

### Methodology — reproduce it yourself

* **Setup**: a release build of `rflow` (v0.1.0, `cargo build --release`), a
  local `anvil` chain (`--block-time 1`, chain id 31337) and the repo's
  compose Postgres, all on one machine.
* **Workflow**: an ERC20 `Transfer` event trigger with a `where:` filter →
  one `send_transaction` step (`wait_for: none`, simulation on — the default).
  Essentially the [`token-transfer-relay` example](/getting-started/examples)
  minus the balance-gate read.
* **Load**: 30 qualifying deposits fired via `cast send`; every one produced
  exactly one run (n=30, all succeeded, zero duplicates).
* **Measurement**: timestamps are the engine's own journal — `workflow_runs.created_at`
  (the claim) to `step_runs.finished_at` of the send step, which with
  `wait_for: none` settles at the relayer queue ack. Percentiles computed in
  SQL over the journal; detection latency compares the event's block timestamp
  to the claim time.
* **Hardware**: Apple M5 Max, 128 GB RAM (a development laptop, not a tuned
  server).
* **In-repo harness**: `cargo run -p rflow_e2e_tests -- --bench` runs a
  self-contained variant (20 sequential deposits, instant-mining anvil,
  unoptimized dev build) and writes `bench-results.json` with every sample,
  the full methodology, and on-chain receipt verification for each tx. Its
  numbers (\~32 ms p50 claim → send settled on a dev build) are consistent
  with the release-build table above.

### Honest caveats

* **Local RPC.** anvil answers `eth_call`/`eth_estimateGas` in microseconds; a
  real provider adds its network round-trips to the \~25 ms (two RPC calls sit
  inside the measured window). The number isolates *rflow's* overhead — it is
  the part of the stack rflow can promise.
* **Detection is poll-bound in this setup.** The 0.83 s p50 from block
  timestamp to claim reflects the indexer's block polling against a 1-second
  chain, and block timestamps have 1-second granularity. Tightening
  `block_poll_frequency` ([networks config](/config/networks)) shrinks it; on
  real chains the block interval (12 s on mainnet) dwarfs this component
  entirely. (`ws:` is parsed but not wired to the engines yet, so it does
  not help here.)
* **Queued, not confirmed.** The relayer owns everything after the queue —
  broadcast, gas bidding, inclusion. End-to-end "event → CONFIRMED" is
  chain-time dominated (block interval × your
  [`confirmations`](/config/networks#core-fields) depth) and would say nothing
  about the engine.
* **One machine, one process, modest n.** n=30 on a dev laptop is a smoke-level
  benchmark for the hot path, not a load test. Concurrency limits
  (`max_concurrent_runs`, group lanes) were not stressed here.

### Why no competitor comparison table?

The obvious candidates (Defender, Tenderly Web3 Actions, Gelato) are hosted
services in a different category: their event→action latency includes their
detection infrastructure, queueing and multi-tenant scheduling, none of which
is publicly benchmarkable in a controlled way — numbers we could publish would
be unfair in one direction or the other. The architectural difference stands
on its own: rflow's trigger-to-relayer path is a function call inside one
process on your hardware, plus two RPC round-trips to *your* provider.

### Where throughput actually goes

For capacity planning, the bottlenecks in practice, in order:

1. **Your RPC provider** — simulation + gas estimation are two calls per send;
   backfills are `eth_getLogs`-bound (`max_block_range`, CU budgets).
2. **Postgres** — every claim, step and settle is a journaled write. Give it
   real storage; it is the durability you are paying for.
3. **The chain itself** — inclusion and confirmation depth; rflow just waits
   well (durably parked, not spinning).

See [Self-hosting → Sizing](/self-hosting#sizing).


## CLI

The `rflow` binary is a pure interface over the core engine. Every command accepts
`--path <dir>` (short `-p`) to point at a project directory; the default is the
current directory.

```bash
rflow --help
```

```
Blazing fast EVM workflow engine built in rust

Usage: rflow <COMMAND>

Commands:
  new        Create a new rflow project (alias: init)
  templates  Browse, inspect, check and author templates (builtin + community registry)
  add        Add a workflow (from a template), network, contract, relayer or notification channel to rflow.yaml
  doctor     Check local dependencies (Docker, Foundry, Postgres, Node) and project readiness
  explain    Plain-English breakdown of what a workflow does (static, from rflow.yaml)
  abi        Fetch, inspect and reverse-lookup contract ABIs
  contract   Contract helpers - `contract add` fetches the verified ABI when --abi is omitted
  import     Convert another platform's config into an rflow project
  start      Validate then boot the engines (lazy), reconcile relayers, recover and run
  validate   Strict collect-all validation of rflow.yaml
  lint       Opinionated safety lint over rflow.yaml (policy-driven, static, no DB)
  ci         One-command CI gate: validate + lint + schema/template/plan/test checks
  schema     Print the JSON Schema for rflow.yaml (editor autocomplete/validation)
  trigger    Manually fire a workflow
  ls         List workflows: state, trigger, cursor, runs today
  status     Engine health, chains, relayer registry, recent runs
  tables     List the queryable tables (indexed event tables + the rflow journal)
  runs       Inspect the run journal
  history    Explore workflow run history (a richer `runs list`); subcommands: txs, approvals, waiting, export
  approve    Approve a parked send (by approval id or run id)
  reject     Reject a parked send (by approval id or run id)
  approvals  List send approvals
  state      Durable-state dashboard + repair (inspect | cursors/waits/delays/circuit)
  cursors    Inspect (ls) or move (set) trigger cursors
  waits      Inspect (ls) or cancel parked saga waits
  delays     Inspect (ls) or wake parked durable delays
  circuit    Inspect (ls) or reset circuit breakers
  budgets    Inspect durable spend budgets (consumed / reserved / remaining)
  spend      Native spend history: gas + value by workflow / relayer / network; subcommand: export
  token      Manage named API bearer tokens for config.server.auth
  secrets    Inspect declared secrets and verify external-provider resolution (never prints values)
  relayers   Manage relayer wallet mappings
  workflow   Pause or resume a workflow
  list       Inspect and mutate runtime watchlists (`lists:`)
  mcp        Serve the Model Context Protocol over stdio (AI agent/editor integration)
  replay     Replay a workflow over historical blocks in an isolated session (dry-run by default), or manage replay/test sessions (`ls` / `prune`)
  versions   Inspect the deployed config version history (ls | show <id> | diff <a> <b>)
  plan       Semantic diff of a config change + active runtime conflicts (the deploy gate)
  rollback   Reconstruct a stored config version back to rflow.yaml (structure; secrets stay placeholders)
  retention  Plan or run journal retention (history pruning driven by config.retention)
  archive    Export a redacted JSONL archive of runs + steps + approvals + failures in a date range
  command    Debug a single `command:` step in isolation (no signer, no db, no run)
  test       Execute one workflow once in dry-run mode from a fixture or a real transaction
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
```

### rflow new

```bash
rflow new [--output <dir>] [--name <project-name>] [--template <id>] [--yes]
          [--answer key=value ...] [--answers-file answers.yaml]
          [--registry github:owner/repo[@branch]]
```

Scaffolds a project from the **template registry** (`rflow templates ls`):
`rflow.yaml`, ABIs, `.env` + `.env.example`, `docker-compose.yml` (postgres on
`localhost:5448`), a `.gitignore` and a `.rflow/template-lock.yaml` recording the
install (template id, version, answers). Interactive on a TTY — a template picker
(id + risk + summary), then one typed prompt per template input; `--yes` (or a
non-TTY) fills every input from its default. `--answer key=value` and
`--answers-file` drive it non-interactively (CI/agents); every answer is
**type-checked before rendering** (addresses, cron expressions, durations, …).

`--template community/<id>` installs from the
[community registry](/templates/community-registry) — fetched SHA-pinned and
hash-verified from the rflow repo, gated by the community doctor profile and
a provenance banner before anything renders (`--registry` points the same
mechanism at a fork, loudly labeled UNTRUSTED). The interactive picker's
final entry fetches the community index and lists its ids.

Legacy scaffold ids keep working: `transfer-alert`, `cron-report` and
`treasury-approval` resolve to their registry equivalents via aliases;
`liquidation-keeper`, `webhook-relay` and `blank` still scaffold through the
pre-registry renderer until converted. Templates with `requires.signer` get a
DEV-ONLY generated mnemonic in `.env` (never in `.env.example`). Aliased as
`rflow init`. Refuses to overwrite an existing `rflow.yaml`, leaves an existing
`.env` untouched, and ends with `rflow validate` + next commands.

See [Scaffolding](/getting-started/scaffolding) for the wizard walkthrough.

### rflow templates

```bash
rflow templates ls [--category <c>] [--risk <r>] [--json]
rflow templates ls --community [--registry github:owner/repo[@branch]]
rflow templates search <query>
rflow templates show <id>
rflow templates inspect <id> --json
rflow templates doctor <id | --all>
rflow templates index [--dir <repo-root>] [--check [--against <baseline-index.json>]]
rflow templates scaffold <id> [--dir <path>]
rflow templates snapshot <id> [--dir <path>]
```

Browse, inspect, check and author templates. `ls` prints
id/category/risk/summary (categories: treasury, monitoring, keeper, intents,
bridge-ops, governance, security, relayers, offchain, examples; risk labels:
`monitor_only`, `prepares_tx`, `money_moving`, `admin`, `experimental`);
`ls --community` fetches the [community registry](/templates/community-registry)
index instead — pinned to the branch head commit, `--registry` points at a
fork. `search` matches id/title/summary. `show` prints the human detail:
generated files, typed inputs with defaults, required
signer/relayers/ABIs/secrets, declared interfaces/endpoints, the safety
profile and the docs page (deprecated templates are labeled). `inspect`
prints the raw manifest as JSON for agents/tooling. `doctor` proves a bundled
template is shippable — manifest parses strictly, declared outputs match the
packaged files, interface surfaces verify (recomputed selectors/topic0s),
inputs are well-formed, the sample answers render a project that passes
`rflow validate`, the committed snapshot matches, and the docs page exists
(skipped outside the repo). Exit 1 on any failure.

The last three are the community-contribution tools: `index` regenerates
`templates/community/index.json` (per-file sha256 pins; `--check` is the CI
gate — byte-exact index + immutable versions, `--against` enforces the same
immutability vs a baseline index from the base branch). `scaffold` writes a
compliant community-package skeleton that passes the community doctor
profile as soon as `snapshot` generates its `tests/expected-rflow.yaml`.

```
Browse, inspect, check and author templates (builtin + community registry)

Usage: rflow templates <COMMAND>

Commands:
  ls        List templates: id, category, risk, summary
  search    Keyword search over template id/title/summary
  show      Human-readable detail for one template
  inspect   Machine-readable manifest for agents/tooling (always JSON)
  doctor    Validate bundled template(s): manifest, files, inputs, sample render, snapshot, docs page
  index     Regenerate templates/community/index.json (per-file sha256 pins over every community package)
  scaffold  Write a compliant community-package skeleton (the submission starting point - see templates/community/SUBMITTING.md)
  snapshot  Render an on-disk package with its answers.sample.yaml and write tests/expected-rflow.yaml (the community snapshot regenerator)
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
```

See the [templates guide](/templates), the
[community registry](/templates/community-registry) and the
[use-case recipes](/use-cases).

### rflow add

```bash
rflow add [--path <dir>] workflow <template-id> [--name <wf>] [--answer k=v ...] [--answers-file <f>] [--dry-run] [--yes] [--registry <github:owner/repo[@branch]>]
rflow add [--path <dir>] network       [--name <n>] [--chain-id <id>] [--rpc <url|${ENV}>] [--ws <url>] [--confirmations <n>]
rflow add [--path <dir>] contract      [--name <n>] [--abi <path>] (--network <net> --address <0x..> | --addresses net=0x,net=0x)
rflow add [--path <dir>] relayer       [--name <n>] [--networks a,b] [--speed SLOW|MEDIUM|FAST|SUPER]
rflow add [--path <dir>] notification  [--name <n>] (--telegram | --slack | --discord | --pagerduty | --opsgenie | --twilio) [env flags]
```

`add workflow` composes a **template** into an existing project: it renders the
template with your answers and merges its contracts, relayers, constants,
secrets, lists, notification channels and workflow into `rflow.yaml`
(comment-preserving), copying packaged files (ABIs) alongside. Inputs already
satisfied by the project (its name, its single network) are not re-asked; on a
TTY the remaining inputs are prompted. Collisions follow the registry rules —
an identical entry is **reused** silently, a same-ABI/subset-addresses contract
is reused with a warning, a conflicting entry is a hard error, and a taken
workflow name demands `--name <new-name>`. `--dry-run` prints the plan without
writing; a successful add appends to `.rflow/template-lock.yaml`, refuses any
change that would introduce a validation error, and prints which env vars to
set. A multi-workflow template (e.g. `safe-monitor`) splices **every** workflow
it declares, in authored order; `--name` only applies to single-workflow
templates. `community/<id>` composes a
[community template](/templates/community-registry) the same way — fetched
SHA-pinned + hash-verified, gated by the community doctor profile first.

```
Add a workflow from a template into the existing rflow.yaml (see `rflow templates ls`)

Usage: rflow add workflow [OPTIONS] <TEMPLATE>

Arguments:
  <TEMPLATE>  The template id, e.g. `large-transfer-alert`

Options:
      --name <NAME>
          Rename the added workflow (required when the template's workflow name already exists in rflow.yaml)
  -p, --path <PATH>
          optional - The path of the project, default will be where the command is run
      --answer <KEY=VALUE>
          Template answer as key=value (repeatable)
      --answers-file <FILE>
          YAML file of template answers (`key: value` scalars)
      --dry-run
          Print the merge plan without writing anything
      --yes
          Non-interactive: no prompts, manifest defaults fill missing inputs
      --registry <GITHUB:OWNER/REPO[@BRANCH]>
          Fetch `community/<id>` templates from this registry instead of the default rflow repo (`github:owner/repo[@branch]`). Non-default registries are UNTRUSTED and require confirmation
  -h, --help
          Print help
  -V, --version
          Print version
```

The other four subcommands incrementally grow an existing `rflow.yaml` — the
counterpart to `rflow new`.
`add` **appends to the right top-level section and preserves the rest of the file
byte-for-byte** (comments, ordering, formatting, trailing newline). It never
parses the whole document to a value and re-serializes it, so your comments on a
money config survive. It expects the 2-space indentation style `rflow new`
scaffolds; a section in another style (zero-indented lists, 4-space indents) makes
the add refuse with the file untouched.

Interactive on a TTY (a network-preset picker, a channel-kind menu, env-var
prompts), and fully flag-driven for CI/agents/non-TTY. A non-TTY run with a
required flag missing errors with exactly what is needed.

Before writing, `add` validates the **merged** config in memory and **refuses**
(exit 1, file untouched) any change that would introduce a hard validation error —
a duplicate name, an unknown network reference, a bad address, or a relayer with
no signer. Errors that were already present before the add are surfaced but do not
block. Every successful add then runs `rflow validate` and prints the exact next
command(s), including a `rflow doctor` hint.

Env-var flags take the **variable name** and are rendered as a `${VAR}`
placeholder; when only the kind flag is given they default to conventional names
(`TG_BOT_TOKEN`/`TG_CHAT_ID`, `SLACK_WEBHOOK_URL`, `DISCORD_WEBHOOK_URL`,
`PAGERDUTY_ROUTING_KEY`, `OPSGENIE_API_KEY`, `TWILIO_ACCOUNT_SID`/`TWILIO_AUTH_TOKEN`).

```
Add a workflow (from a template), network, contract, relayer or notification channel to rflow.yaml

Usage: rflow add [OPTIONS] <COMMAND>

Commands:
  workflow      Add a workflow from a template into the existing rflow.yaml (see `rflow templates ls`)
  network       Add a network to `networks:`
  contract      Add a contract to `contracts:`
  relayer       Add a relayer wallet to `relayers:`
  notification  Add a notification channel to `notifications.channels:`
  help          Print this message or the help of the given subcommand(s)

Options:
  -p, --path <PATH>  optional - The path of the project, default will be where the command is run
  -h, --help         Print help
  -V, --version      Print version
```

`--path` is global, so it works either before or after the subcommand
(`rflow add --path proj network ...` and `rflow add network --path proj ...` are
equivalent).

### rflow doctor

```bash
rflow doctor [--path <dir>] [--profile <name>] [--deep] [--json]
```

Two sections, one command:

* **Quick readiness** — Docker (daemon reachable), Foundry (`anvil` + `cast` on
  `PATH`, with versions), Postgres (reachable via the project's
  `config.db_connection`), Node (optional, for the docs), plus the `rflow.yaml`
  validate summary. Every dependency is marked `ok` / `missing` / `n/a` with a
  one-line "how to install or start" hint.
* **Deep operational suite** — runs automatically whenever a project is present
  (`--deep` only makes it explicit; without a project only the tool checks run):
  yaml validation summary, **profile merge correctness** (the selected
  `--profile` must apply cleanly and validate — other declared profiles are
  checked in passing), DB connect + `rflow` schema/migration presence, per-network
  RPC (**`eth_chainId` must match the declared `chain_id`** — a mismatch is an
  error), `finalized`-tag support (advice, probed only when a workflow uses
  `finalized`), best-effort archive depth (advice, probed only when a workflow
  backfills history), contract sanity (ABI parses, addresses EIP-55
  checksum-valid), relayer mapping presence (`rflow.relayers`) + native **balance
  fetch with a low-balance warning**, signer shape (raw/private-key env vars
  resolve; cloud providers get a config-shape note — no live call), notification
  channel delivery probes, **webhook auth warnings** (no auth on a money workflow),
  trigger cursor lag vs head, approval-gate posture (`on_timeout: proceed`
  warns), reorg/confirmation guidance for send workflows, and
  rate-limit/budget/circuit **coverage notes** for money workflows.

Every check carries a severity: `error` / `warning` / `advice` / `info`.
**Exit code: non-zero iff an error-severity check fails** — warnings, advice and
info never block, so `rflow doctor` is safe to gate CI/deploys on. `--json`
prints one stable machine-readable report (`version`, `quick`, `checks`,
`summary`, `ok`) on stdout for exactly that.

```
Check local dependencies (Docker, Foundry, Postgres, Node) and project readiness

Usage: rflow doctor [OPTIONS]

Options:
  -p, --path <PATH>        optional - The path of the project, default will be where the command is run
      --profile <PROFILE>  Diagnose the merged view after applying a `profiles.<name>` overlay (a broken profile is an error-severity failure)
      --deep               Run the full operational suite (DB schema, RPC chain ids + capabilities, relayer mappings/balances, channels, webhooks, approvals, coverage). Default ON when a project is present — the flag only forces it explicitly
      --json               Print one stable machine-readable JSON report on stdout (the CI gating surface). Exit code stays: non-zero iff an error-severity check fails
  -h, --help               Print help
  -V, --version            Print version
```

`validate --preflight` runs the connectivity subset of these same checks (same
functions, no duplicated logic) — but preflight keeps its stricter historical
rule: *any* failed check fails the command. The full check catalogue, JSON shape
and CI gating pattern live in
[Doctor & explain](/operations/doctor-and-explain).

### rflow explain

```bash
rflow explain [<workflow>] [--risk] [--json] [--path <dir>] [--profile <name>]
```

A **static** plain-English narrative of what a workflow does, straight from
`rflow.yaml` — no network, no database. With no argument: one summary block per
workflow (trigger sentence, step chain, risk label
`monitor_only` / `prepares_tx` / `money_moving` — the template-registry
vocabulary). With a workflow: the full breakdown — the trigger (kind,
contract/event/schedule, conditions, confirmations), each step in order (what it
does, what it depends on, `if:` conditions), **WHAT SENDS MONEY** (each
`send_transaction`: network, relayer, decoded call target, value/args source),
**WHAT BLOCKS MONEY** (simulation, `assert_sim`, `recheck`, `valid_for`, approval
gates, gas caps, permissions/budgets, relayer policy, rate limit, circuit
breaker, concurrency), **ON FAILURE** (retries, `on_failure` route, `finally`,
`workflow_error` watchers), **ON REORG**, **REPLAY / DRY-RUN** behaviour (one
honest paragraph: sends stop pre-broadcast; waits settle unless `--with-waits`)
and **EXTERNAL SYSTEMS** (HTTP hosts, channels, local commands).

`--risk` prints only the money sections plus a reviewer checklist
(`[x]`/`[ ]` per safeguard and a `verdict: N of 11` line) — enough context to
approve or reject a production change. `--json` emits the same data structured.
Output is deterministic, and every render ends with the honesty footer: explain
describes the *configuration*, not runtime guarantees. The PR-review pattern is
in [Doctor & explain](/operations/doctor-and-explain#--risk--the-pr-review-view).

```
Plain-English breakdown of what a workflow does (static, from rflow.yaml)

Usage: rflow explain [OPTIONS] [WORKFLOW]

Arguments:
  [WORKFLOW]  The workflow to explain in full. Omitted = one summary block per workflow

Options:
  -p, --path <PATH>        optional - The path of the project, default will be where the command is run
      --risk               Only the money sections (WHAT SENDS / WHAT BLOCKS) plus a reviewer checklist verdict
      --json               Print the same data as one structured JSON object on stdout
      --profile <PROFILE>  Explain the merged view after applying a `profiles.<name>` overlay
  -h, --help               Print help
  -V, --version            Print version
```

### rflow abi

```bash
rflow abi fetch (--network <name> | --chain-id <id>) --address <0x..> [--out <file>] [--source sourcify|etherscan] [--name <base>]
rflow abi inspect <file.json> [--json]
rflow abi find-event    (<file.json|abis-dir> <topic0>        | --project <topic0>)        [--json]
rflow abi find-function (<file.json|abis-dir> <sel-or-sig>    | --project <sel-or-sig>)    [--json]
```

`abi fetch` pulls the **verified** ABI for an address and writes it
pretty-printed under the project's `abis/` dir. Source order: **Sourcify first**
(keyless), then **Etherscan v2** (`https://api.etherscan.io/v2/api?chainid=…`,
needs `ETHERSCAN_API_KEY` — when the key is absent and sourcify had no match,
the error says exactly that, per source). `--network` reads the chain id from
`rflow.yaml`; `--chain-id` works with no project at all. The default filename is
`abis/<--name>.json` (or `abis/<address>.json`); re-fetching an identical file
is a no-op, but a file with **different content is never clobbered** — delete it
or pass `--out`.

> **Reproducibility, by design.** The spec'd inline-YAML shortcut
> (`abi: { fetch: ... }` inside `rflow.yaml`) is intentionally **not**
> implemented: a config that fetches ABIs at load time is not reproducible.
> `rflow.yaml` only ever points at **committed ABI files**; the CLI fetches
> once and materialises the file. No config surface changed
> (`rflow.schema.json` is untouched).

`abi inspect` prints every event (name, full signature, **topic0** hash,
indexed params) and every function (name, signature, **4-byte selector**,
mutability); `--json` emits the same rows as JSON.

`abi find-event` reverse-maps a topic0 hash to the event that emits it —
against one ABI file, a directory of ABI json files, or (with `--project`)
every ABI file the project's `rflow.yaml` references. Unparseable json files in
a directory scan are skipped with a warning; no match exits 1 with a
`rflow abi fetch` hint. `abi find-function` is the same lookup for 4-byte
selectors, and also accepts a full signature (`transfer(address,uint256)`),
which it hashes for you.

```bash
rflow abi fetch --network ethereum --address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --name usdc
rflow abi inspect ./abis/usdc.json
rflow abi find-event ./abis 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
rflow abi find-function --project 0xa9059cbb
```

```
Fetch, inspect and reverse-lookup contract ABIs

Usage: rflow abi [OPTIONS] <COMMAND>

Commands:
  fetch          Fetch the VERIFIED ABI for an address (sourcify first, then etherscan) and write it under the project's abis/ dir
  inspect        Show every event (topic0, indexed params) and function (selector, mutability) in an ABI file
  find-event     Find which event a topic0 hash belongs to (one file, a directory of ABIs, or --project for every ABI rflow.yaml references)
  find-function  Find which function a 4-byte selector (or full signature) belongs to
  help           Print this message or the help of the given subcommand(s)

Options:
  -p, --path <PATH>  optional - The path of the project, default will be where the command is run
  -h, --help         Print help
  -V, --version      Print version
```

Related: validation errors for unknown event/function names now carry a
close-match suggestion — `contract 'USDC' has no event 'Transferr' - did you
mean 'Transfer'?` — and the importers hint at `rflow abi find-event` /
`rflow abi fetch` whenever they cannot name an event topic hash locally.
Full guide: [ABIs — fetch, inspect & discover](/config/abis).

### rflow contract

```bash
rflow contract add <Name> --network <net> --address <0x..> [--abi <path>]
```

Adds a contract **by address alone**. With `--abi` it is exactly
`rflow add contract` (the same comment-preserving, validating code path).
Without it, the verified ABI is fetched first (sourcify → etherscan, see
`rflow abi fetch`), written to `abis/<name>.json`, and then wired into
`contracts:` — the command prints what was fetched, the file written, and the
validate result.

```bash
rflow contract add USDC --network ethereum --address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
```

Full guide: [ABIs — fetch, inspect & discover](/config/abis).

```
Add a contract to rflow.yaml - with --abi this is exactly `rflow add contract`; without it the verified ABI is fetched (sourcify -> etherscan), written to abis/<name>.json and wired up

Usage: rflow contract add [OPTIONS] --network <NETWORK> --address <ADDRESS> <NAME>

Arguments:
  <NAME>  Contract registry name, e.g. `USDC`

Options:
      --network <NETWORK>  The network (must exist in rflow.yaml; its chain_id picks the explorer chain when fetching)
  -p, --path <PATH>        optional - The path of the project, default will be where the command is run
      --address <ADDRESS>  The contract address (0x…)
      --abi <PATH>         Use this ABI file instead of fetching one
  -h, --help               Print help
  -V, --version            Print version
```

### rflow import

```bash
rflow import defender <serverless.yml> [--output <dir>]
rflow import gelato <tasks.json> [--output <dir>]
```

Converts an OpenZeppelin Defender-as-Code `serverless.yml` or Gelato Automate task
JSON into a complete rflow project that passes `rflow validate` as-is, with a
summary table of what mapped and a `MIGRATION-NOTES.md`. See
[Migrate from Defender](/migrate/from-defender) and
[Migrate from Gelato](/migrate/from-gelato).

### rflow start

```bash
rflow start [--path <dir>] [--yes] [--standby] [--watch] [--profile <name>]
```

The whole boot, in order: load `.env` → validate `rflow.yaml` (warnings printed) →
connect Postgres + apply the `rflow` schema → take the project advisory lock →
generate runtime engine configs → boot the relayer (only if a signer is declared) →
[reconcile relayers](/config/relayers#lifecycle) → recovery pass → boot the indexer
(only if chain triggers exist) → run. Ctrl-C / SIGTERM shuts down gracefully.

* `--yes` skips confirmation prompts (e.g. creating new relayer wallets).
* `--standby` boots as an HA standby: wait for the project leadership lock instead
  of exiting when another instance holds it (overrides `config.ha.standby`) — see
  [High availability](/self-hosting#high-availability-leaderstandby).
* `--watch` hot-reloads `rflow.yaml` on valid changes; invalid edits keep the
  running config (see [Observability](/observability#watch-mode--rflow-start---watch)).
* `--profile <name>` applies a [`profiles.<name>`](/config/profiles) overlay
  before booting.

### rflow validate

```bash
rflow validate [--path <dir>] [--preflight] [--preflight-notify] [--profile <name>]
```

Strict, collect-all: unknown keys, missing refs (networks, contracts, relayers,
channels, lists), ABI/function checks, expression analysis, signer shape, and
[reorg advice](/reorgs#per-chain-guidance) — all errors reported at once, advice in
yellow, errors in red.

`--preflight` additionally runs live connectivity checks — every RPC's
`eth_chainId` compared against the declared `chain_id`, database connectivity,
and notification channels — as an ok/fail table, exiting 1 on any failure.
Slack/Discord webhooks get a TCP reachability check unless `--preflight-notify`
is passed (which posts a real test message). It also runs
[`command`](/workflows/steps/command) checks: each command step's executable
resolves (on `PATH` or as a project-relative path), any local script argument
exists, and a known interpreter reports its version. See
[Observability](/observability#preflight-checks--rflow-validate---preflight).

`--profile <name>` validates the merged view a
[profile](/config/profiles) boots.

### rflow lint

```bash
rflow lint [--path <dir>] [--strict] [--profile <name>] [--json]
```

The opinionated safety linter — `validate` asks "is this correct?", `lint`
asks "is this **safe to run in production**?": unsimulated sends, missing gas
ceilings, head-fired money, unauthenticated webhooks, missing idempotency,
timeout-proceed approvals, public ports on money projects. Fully static (no
database, no network, and usually no `.env` needed — lint prefers the raw
`${VAR}` view).

Findings follow an honest three-tier severity: recommended defaults **warn**
(exit 0), knobs written into the optional top-level `policy:` block **deny**
(exit 1) when violated, and `--strict` (or `policy.strict: true`) promotes
every warning to a failure. Suppressions live under `policy.suppress` and
require a written `reason` (the file does not parse without one). Every
finding prints its fix and a docs link.

```
Opinionated safety lint over rflow.yaml (policy-driven, static, no DB)

Usage: rflow lint [OPTIONS]

Options:
  -p, --path <PATH>        optional - The path of the project, default will be where the command is run
      --strict             Promote every warning to a failure (same as `policy.strict: true`)
      --profile <PROFILE>  Lint the merged view after applying a `profiles.<name>` overlay (a profile may carry its own stricter `policy:`)
      --json               Machine-readable report on pure stdout (errors go to stderr)
  -h, --help               Print help
  -V, --version            Print version
```

See [Safety lint & the CI gate](/operations/lint-and-ci) for every rule, the
`policy:` reference and suppression syntax.

### rflow ci

```bash
rflow ci [--path <dir>] [--profile <name>] [--strict] [--preflight] [--json]
```

The one-command CI gate: validate → lint → committed-schema check →
template-lock check → [config plan](/operations/versioning-and-plan) against
the latest stored version (when the database is reachable) → every
`tests/<workflow>[.case].json` fixture as a dry-run — plus the live
connectivity preflight with `--preflight`. Stages whose prerequisites are
absent are **skipped with a reason**, never silently passed. Exits non-zero
iff a gating stage fails; `--json` keeps stdout pure for the versioned
machine report.

```
One-command CI gate: validate + lint + schema/template/plan/test checks

Usage: rflow ci [OPTIONS]

Options:
  -p, --path <PATH>        optional - The path of the project, default will be where the command is run
      --profile <PROFILE>  Run every stage against a `profiles.<name>` overlay
      --strict             Lint in strict mode (warnings fail)
      --preflight          Also run the live connectivity preflight (RPCs, database, notification channels) - the only stage that dials out
      --json               Machine-readable report on pure stdout (errors go to stderr)
  -h, --help               Print help
  -V, --version            Print version
```

See [Safety lint & the CI gate](/operations/lint-and-ci#rflow-ci) for the
stage table and a ready-to-copy GitHub Actions workflow.

### rflow schema

```bash
rflow schema > rflow.schema.json
```

Prints the JSON Schema for `rflow.yaml` — wire it into your editor for
completion and validation (see
[editor setup](/config/profiles#editor-autocomplete-for-rflowyaml)).

### rflow trigger

```bash
rflow trigger <workflow> [--input key=value ...] [--path <dir>]
```

Manually fire a workflow. `--input` pairs are exposed to expressions as `inputs.*`.

### rflow ls

```bash
rflow ls [--path <dir>]
```

Workflows with their state (running/paused), trigger summary, cursor (last processed
block for event triggers), and runs today.

### rflow status

```bash
rflow status [--path <dir>]
```

Engine health, chains, relayer registry and recent runs — plus the HA leadership
state (leader running / no leader, via a lock probe). Workflows with
[`liveness:`](/operations/unattended-ops#liveness--alert-when-a-workflow-goes-silent)
get a liveness table (last run, `max_silence`, OK/BREACHED), and detected
indexer stalls print per network.

### rflow tables

```bash
rflow tables [--path <dir>]
```

The discoverability command for the [query layer](/workflows/steps/query):
lists every queryable table in the project's Postgres — the indexed event
tables (`rflow_indexer_rflow_<workflow>.*` for event triggers,
`rflow_indexer_rflow_idx_<contract>.*` for
[`index_events`](/config/contracts#index_events--index-only-analytics)) and
the `rflow.*` journal — with columns and row counts, plus the naming rule as
a footer. Schemas the config implies but the database does not have yet
(fresh project, indexer not booted) are footnoted as "declared but not
created yet" so nobody mistakes a new project for a broken one.

### rflow runs

```bash
rflow runs list [--failed] [--limit <n>]   # journal: run list, per-step status (default 20, newest first)
rflow runs show <id>                       # one run in detail: outputs, tx links, attempts, approvals, reorg responses
rflow runs retry <id>                      # re-fire a dead-lettered run
rflow runs diff <a> <b> [--json]           # compare two runs: trigger, step outputs, errors, tx summaries
rflow runs timeline <id> [--json]          # chronological step/attempt/approval/tx trace of one run
```

`runs diff` answers "what changed between a good run and a bad one?" — it lines
up the trigger payloads, per-step outputs, errors and tx summaries of two runs
(both secret-redacted). `runs timeline` folds one run's steps, attempts,
approval decisions, reorg-response steps and tx lifecycle into a single
time-ordered view — the CLI form of the [history explorer](/operations/history-explorer)'s
run detail. Both accept `--json` for automation.

### rflow history

```bash
rflow history [--workflow <wf>] [--status <s>] [--trigger <kind>] [--network <net>] \
              [--since <24h|7d|RFC3339>] [--session <live|replay|test|any>] \
              [--limit <n>] [--cursor <c>] [--json]   # a richer `runs list`, keyset-paginated
rflow history txs [--workflow <wf>] [--network <net>] [--status <s>] [--since <7d>] \
              [--limit <n>] [--cursor <c>] [--json]   # every send attempted (queued/submitted/settled)
rflow history approvals [--workflow <wf>] [--all] [--since <7d>] \
              [--limit <n>] [--cursor <c>] [--json]   # approvals (pending; --all adds decided/expired)
rflow history waiting [--workflow <wf>] [--limit <n>] [--cursor <c>] [--json]
                                                       # runs parked right now (tx / delay / event / approval)
rflow history export [--workflow <wf>] [--since <30d>] [--until <ts>] \
              [--format json|csv] [--out <file>]      # a redacted audit trail (secrets always stripped)
```

The [history explorer](/operations/history-explorer) surface without the UI —
the same core [`rflow_core::history`](/operations/history-explorer#the-shared-query-layer)
query layer the `/api/history/*` endpoints use, so the CLI and the UI never
diverge. Every subcommand is **keyset-paginated** (a `--cursor` from one page's
`next_cursor` fetches the next, newest first — never a skip or a duplicate) and
every payload is **secret-redacted** (declared `secrets:`, secret-typed config
fields and `${VAR}` env values are rendered `<redacted>`). `--json` is available
everywhere for automation, and `export` is redacted by default with no raw-payload
flag.

### rflow versions / plan / rollback

```bash
rflow versions ls [--json]                # deployed config history: id, hash, created, run count
rflow versions show <id> [--json]         # a version's summary + per-workflow definitions
rflow versions diff <a> <b> [--json]      # semantic delta between two stored versions

rflow plan [--from-version <id>] [--to <path>] [--profile <name>] [--json]
                                          # semantic diff + active runtime conflicts (exits non-zero on any error)

rflow rollback <version-id> [--output <path>] [--yes]
                                          # reconstruct a stored version to rflow.yaml (structure; secrets stay <redacted>)
```

The [versioning & config plan](/operations/versioning-and-plan) surface: every
boot fingerprints the profile-merged, secret-redacted config into
`rflow.config_versions` and stamps that `config_version` onto every run
(visible in `rflow runs show` and `rflow ls`). `rflow plan` is the deploy gate
— it flags dangerous changes (money-moving sends, lowered confirmations,
weakened approvals/caps) and the parked work they collide with, and exits
non-zero on any error-severity item for CI.

### rflow approve / reject / approvals

```bash
rflow approvals ls [--all]                # pending approvals (--all includes decided/expired)
rflow approve <id> [--yes] [--token <t>]  # approve a parked send (approval id or run id)
rflow reject <id> [--reason "why"] [--token <t>]  # reject it (the reason is journaled)
rflow approvals expire <id> [--reason "why"] --yes   # expire a pending approval (repair)
```

The human half of [approval gates](/approvals). `approve` shows the prepared
transaction and asks for confirmation (`--yes` skips it); an approved send is
re-checked and re-simulated before it broadcasts. On an
[N-of-M policy approval](/approvals#approval-policies--n-of-m-quorums) your
identity must be PROVEN: pass `--token <api-token>` (or set
`RFLOW_API_TOKEN`) — the token's name maps to your
`approvers.<member>.cli.token`, each member counts once, and the first
rejection vetoes by default. `approvals expire` is the
[repair](/operations/state-inspection-and-repair) path for a gate nobody
answered: it prints a plan, needs `--yes`, and flips a pending approval to
`expired` so the run takes its `on_timeout` path (no send is broadcast).

### rflow state / cursors / waits / delays / circuit

```bash
rflow state inspect [--workflow <wf>] [--json]   # durable-state dashboard (read-only)

rflow cursors ls [--workflow <wf>]               # trigger cursors
rflow cursors set <wf> <network> --block <n> --yes   # re-scan or skip ahead

rflow waits ls [--workflow <wf>]                 # runs parked on a wait_for:
rflow waits cancel <run-id> --reason "why" --yes # terminalize a stuck saga wait

rflow delays ls [--workflow <wf>]                # runs parked on a durable delay
rflow delays wake <run-id> --yes                 # wake a parked delay early

rflow circuit ls [--workflow <wf>]               # circuit-breaker state
rflow circuit reset <workflow> --yes             # clear a tripped breaker
```

[State inspection & repair](/operations/state-inspection-and-repair) — supported,
journal-aware recovery for known stuck states instead of manual SQL. `state
inspect` (and the `ls` listings) are read-only. Each repair mutation prints a
**plan first**, requires `--yes`, refuses on a wrong precondition or a run with
an in-flight send, and writes an `rflow.operator_audit` row. No repair can create
a duplicate send: repairs terminalize stuck work rather than re-run money-moving
steps, and lowering a cursor re-scans safely (already-claimed events dedupe by
`trigger_key`).

### rflow retention / archive

```bash
rflow retention plan                      # what WOULD be pruned per class (reads only)
rflow retention prune --dry-run           # print the plan, delete nothing
rflow retention prune --yes               # prune per config.retention (deletion needs --yes)

rflow archive export --since 2026-01-01 [--until 2026-03-01] [--out <dir>] [--format jsonl]
                                          # dump runs+steps+approvals+failures+reorgs+sessions to redacted JSONL
```

Operator-driven [history retention](/operations/retention-and-archive), driven
by `config.retention`. `retention plan` reports per-class counts + age span
without deleting; `retention prune` refuses to delete without `--yes` (it prints
the plan instead) and, with `archive_before_prune`, exports the archive first
and aborts the whole prune if that export fails. Active runs, pending approvals,
parked waits/delays, in-flight sends and running reorg responses are never
prunable. `archive export` redacts secrets by default; a relative `--out` (and
the default `./archives`) resolves against the project dir.

### rflow budgets ls

```bash
rflow budgets ls                          # per-asset consumed / reserved / remaining
```

Shows each [spend budget](/workflows#budgets) with its cap and, per asset,
`consumed` (reserved in-flight + spent settled), `reserved`, and `remaining`
inside the current rolling window — read straight from `rflow.budget_reservations`.

### rflow spend

```bash
rflow spend [--workflow <wf>] [--relayer <r>] [--network <net>] \
            [--since <30d|24h|RFC3339>] [--json]
                                          # grouped summary: gas + value by workflow / relayer / network,
                                          # totals + reverted-loss subtotal
rflow spend export [--format csv|json] [--workflow <wf>] [--relayer <r>] \
            [--network <net>] [--since <30d>]
                                          # raw ledger entries to stdout (stable CSV columns; exact wei)
```

The operator view over the receipt-derived
[native spend ledger](/operations/spend-tracking) (`rflow.native_spend`):
what rflow actually paid in gas and moved in native value, per settled send.
Human tables format amounts as the native unit; `--json` and `export` keep
stdout pure and carry **exact wei** as decimal strings. Reverted sends appear
with their burned gas as the *reverted loss* subtotal (a revert moves no
value). The same numbers back `GET /api/spend`, the explorer's Spend view and
the [`max_gas_spend`](/workflows/budgets#max_gas_spend--the-gas-circuit-breaker)
budget circuit breaker.

### rflow relayers

```bash
rflow relayers ls                    # every name → wallet mapping (incl. orphans), live balances
rflow relayers balance [--json]      # balances per chain with low-balance flags
rflow relayers sync                  # standalone reconcile: create+clone wallets, print funding table
rflow relayers rename <old> <new>    # re-label a mapping WITHOUT creating a new wallet

rflow relayers discover [--json]     # list relayers in the shared rrelayer db + signer compatibility
rflow relayers import <name> --id <uuid> --network <net>
                                     # adopt an existing relayer (derived address verified FIRST)
rflow relayers import --interactive  # pick from discover, prompt for the local name
rflow relayers verify-imports        # ok/mismatch/not-found per import.id — non-zero on failure (CI)

rflow relayers funding-plan [--json] # balance vs estimated need per relayer/network
rflow relayers qr <name> [--network <net>] [--address-only]
                                     # the address + a terminal QR code (fund from a wallet app)
rflow relayers topup-plan [--json]   # underfunded relayers and their shortfalls
rflow relayers topup --from <name> --to "*"|<name> --network <net> \
            [--amount <wei> | --to-target] --yes
                                     # fund shortfalls from a funding relayer (plan first, --yes to send)
rflow relayers history [--since 30d] [--relayer <r>] [--json]
                                     # recent gas spend per relayer + top-up actions
```

`sync` lets you create and fund wallets before ever running a workflow. `rename` is
the answer to the [rename honesty check](/config/relayers#renames-are-handled-honestly).
The [import flow](/config/relayers#importing-existing-rrelayer-relayers) adopts
relayers created by other services sharing the rrelayer database — a signer
mismatch refuses before anything is written. The
[funding operations](/config/relayers#funding-operations) estimate need from a
documented gas-headroom heuristic (workflow count × headroom sends × safety ×
live gas price × typical gas — every factor overridable), and `topup` broadcasts
normal relayer sends that land in the
[spend ledger](/operations/spend-tracking) + operator audit trail. `funding-plan`,
`topup-plan` and `topup` accept `--typical-gas`, `--sends-per-workflow` and
`--safety-factor` to tune the estimate.

### rflow token

```bash
rflow token create --name <label>   # mint a named API bearer token — prints the plaintext ONCE, stores only its hash
rflow token revoke <id>             # auth stops accepting the token immediately
rflow token ls                      # id / name / created / revoked — never the token itself
```

Named bearer tokens for [`config.server.auth`](/config/config#named-api-tokens).
Auth accepts the config shared token **and** any non-revoked named token, so you
can hand out per-operator/per-dashboard tokens and revoke a leaked one without a
restart or a yaml edit. Only the hex SHA-256 is stored — the plaintext is shown
once at creation. These commands need only `config.db_connection`, not a running
server.

### rflow secrets

```bash
rflow secrets ls        # name / source (env | provider:<name>) / remote key / resolved? / version — never values
rflow secrets doctor    # verify every declared secret resolves; exit non-zero on any provider failure
```

Inspect the [`secrets:`](/config/constants-secrets-lists#secrets) map and verify
[external secret provider](/config/secret-providers) resolution without ever
printing a value. `ls` shows where each secret comes from and whether it
resolves (provider secrets are fetched to report the resolved column and the
provider's version id); `doctor` fetches every provider-backed secret and exits
non-zero when any is missing, denied or unreachable — the same fail-closed
resolution `rflow start` performs at boot, and the same per-secret checks
`rflow doctor` runs in its deep suite. Neither command needs the database or a
running server — only `rflow.yaml` (+ its `.env`).

### rflow workflow

```bash
rflow workflow pause <workflow>     # kill-switch — persisted in Postgres
rflow workflow resume <workflow>
```

### rflow list

```bash
rflow list add <list> <value>        # persists in rflow.list_members — visible to the next where: evaluation
rflow list remove <list> <value>     # removes a runtime member (YAML seeds are config — edit rflow.yaml)
rflow list show [<list>]             # members with provenance (seed/manual/workflow/source) + counts
```

Live mutation of [`lists:`](/config/constants-secrets-lists#lists) watchlists.
Addresses are stored lowercased; membership checks stay case-insensitive.

### rflow mcp

```bash
rflow mcp [--path <dir>]
```

Serves the [Model Context Protocol](/mcp) over stdio so AI agents and editors can
operate the project: validate, inspect the journal, simulate calls, trigger/pause/
retry — with no raw send tool, ever.

### rflow replay

```bash
rflow replay --help
```

```
Replay a workflow over historical blocks in an isolated session (dry-run by default), or manage replay/test sessions (`ls` / `prune`)

Usage: rflow replay [OPTIONS] [WORKFLOW]
       rflow replay <COMMAND>

Commands:
  ls     List replay and test sessions (id, workflow, kind, created, run count)
  prune  Delete replay/test sessions: their rows, indexer schemas and runtime dirs
  help   Print this message or the help of the given subcommand(s)

Arguments:
  [WORKFLOW]
          The workflow to replay (event- or block-triggered)

Options:
  -p, --path <PATH>
          optional - The path of the project, default will be where the command is run

      --from-block <FROM_BLOCK>
          First block of the bounded range

      --to-block <TO_BLOCK>
          Last block of the range (default: the network's current head, pinned at start)

      --with-waits <WAITS.json>
          Deterministic saga wait outcomes: a JSON map of wait-step id -> {"event": …} | {"timeout": true}

      --diff <OTHER_PROJECT_DIR>
          Diff this range against another project's same-named workflow (prints the delta)

      --output <OUTPUT>
          Output format for CI: human | json | junit

          Possible values:
          - human: Human-readable tables (default)
          - json:  A single structured JSON object on stdout
          - junit: A JUnit `<testsuite>` XML on stdout (GitHub Actions / GitLab)
          
          [default: human]

      --live
          DANGER: boot the relayer engine and send REAL transactions while replaying (default is dry-run: simulate + report, never send)

      --yes
          Skip the --live confirmation prompt

      --timeout <TIMEOUT>
          Session budget in seconds (bounded backfill + run drain)
          
          [default: 600]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
```

Backtest an **event- or block-triggered** workflow over a historical block range
in an **isolated session** — dry-run by default (simulate + report, never send).
`--live` sends real transactions and demands you type `send` at a red prompt
(`--yes` skips it). `--with-waits` pins saga [`wait_for`](/workflows/steps/wait-for)
outcomes; `--diff` compares two project versions over the same range (non-zero
exit on difference); `--output json|junit` emits a CI report, and the process
exits non-zero when any replay run failed. Full guide:
[Backtesting](/backtesting).

#### rflow replay ls / prune

```bash
rflow replay ls --help
```

```
List replay and test sessions (id, workflow, kind, created, run count)

Usage: rflow replay ls [OPTIONS]

Options:
  -p, --path <PATH>  optional - The path of the project, default will be where the command is run
  -h, --help         Print help
  -V, --version      Print version
```

```bash
rflow replay prune --help
```

```
Delete replay/test sessions: their rows, indexer schemas and runtime dirs

Usage: rflow replay prune [OPTIONS]

Options:
      --older-than <DUR>  Prune sessions created longer ago than this duration (e.g. 7d, 12h)
  -p, --path <PATH>       optional - The path of the project, default will be where the command is run
      --session <ID>      Prune one session by id
      --all               Prune every replay/test session
  -h, --help              Print help
  -V, --version           Print version
```

`ls` lists every replay/test session (DB rows ∪ orphan runtime dirs). `prune`
deletes the selected sessions — namespaced journal rows, per-session rindexer
schemas and runtime dirs — and **never touches live workflows**. It requires a
selector (`--older-than 7d` / `--session <id>` / `--all`).

### rflow test

```bash
rflow test --help
```

```
Execute one workflow once in dry-run mode from a fixture or a real transaction

Usage: rflow test [OPTIONS] <WORKFLOW>

Arguments:
  <WORKFLOW>
          The workflow to execute once

Options:
  -p, --path <PATH>
          optional - The path of the project, default will be where the command is run

      --event <FIXTURE.json>
          Path to an EVENT fixture json: {"args": {...}, "block_number"?, ...}

      --from-tx <TX_HASH>
          Build the trigger from a real transaction hash (fetches the receipt and decodes the matching trigger event)

      --fixture <FIXTURE.json>
          Path to a fixture json for the workflow's OWN trigger kind (cron/webhook/read/query/block/event)

      --cron-at <ISO8601>
          Cron workflows: the scheduled tick (ISO8601), sugar for a {scheduled_for} fixture

      --read-output <OUTPUT.json>
          Read/query workflows: a json file with the decoded {output}, sugar for --fixture

      --with-waits <WAITS.json>
          Deterministic saga wait outcomes: a JSON map of wait-step id -> {"event": …} | {"timeout": true}

      --output <OUTPUT>
          Output format for CI: human | json | junit

          Possible values:
          - human: Human-readable tables (default)
          - json:  A single structured JSON object on stdout
          - junit: A JUnit `<testsuite>` XML on stdout (GitHub Actions / GitLab)
          
          [default: human]

      --timeout <TIMEOUT>
          Run budget in seconds
          
          [default: 120]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
```

Execute one workflow once in dry-run mode from exactly one trigger source
(`--event` / `--from-tx` / `--fixture` / `--cron-at` / `--read-output` are
mutually exclusive). `--fixture` interprets the file against the workflow's
declared trigger kind (event/cron/webhook/read/query/block). `--with-waits`
pins saga wait outcomes; `--output json|junit` makes it a CI check — the
process exits non-zero when the run did not succeed. `--timeout` bounds the
run (default 120s). Full guide:
[Backtesting](/backtesting#rflow-test--one-run-from-a-fixture).

### rflow command test

```bash
rflow command test <workflow> <step-id> [--input <fixture.json>] [--json]
```

Debug a single [`command`](/workflows/steps/command) step in isolation. The step
renders exactly as a run would — `--input` supplies the dynamic context roots
(`trigger`, `steps`, `state`, …); the static roots
(`constants`/`secrets`/`contracts`/`lists`) come from `rflow.yaml` — then the
command runs **for real** and prints the rendered invocation, the
secret-redacted stdin, the duration, and the parsed output (or the taxonomy
failure). Nothing is signed, sent, journaled, or persisted, and no database is
needed; the process exits non-zero when the command fails, so a fixture doubles
as a CI check. `--json` emits a single machine-readable transcript.


## MCP server

`rflow mcp` serves the [Model Context Protocol](https://modelcontextprotocol.io)
over stdio, so AI agents and editors — Claude Code, Cursor, or anything else
that speaks MCP — can **operate** an rflow project: validate config, inspect
the run journal and indexer cursors, simulate contract calls, and perform the
same journaled, safe mutations the CLI exposes. No other workflow engine ships
this: your agent debugs a dead-lettered run, simulates the fix, and retries it
without ever touching a key.

```bash
rflow mcp [--path <dir>]
```

Long-running; reads JSON-RPC from stdin and writes responses to stdout (logs go
to stderr). Exits cleanly when the client closes stdin. The server reads
`rflow.yaml` fresh on every call and connects to the project's
`config.db_connection` lazily — config-only tools work before Postgres is even
up.

### Claude Code / Cursor setup

Add rflow to your MCP config (`.mcp.json` for Claude Code, `.cursor/mcp.json`
for Cursor):

```json
{ "mcpServers": { "rflow": { "command": "rflow", "args": ["mcp", "--path", "/my/project"] } } }
```

Or one-shot with the Claude Code CLI:

```bash
claude mcp add rflow -- rflow mcp --path /my/project
```

### The safety model

The tool surface is **ops-level, not wallet-level**:

* **Read-heavy by design** — config, journal, cursors and health are all
  read-only queries against `rflow.yaml` and the Postgres journal.
* **`simulate_send` never broadcasts** — it is an `eth_call` through the same
  read providers the engine uses for pre-flight simulation. It never signs,
  never queues, never touches the relayer.
* **Mutations are the journaled safe ops only** — `trigger_workflow` claims a
  manual run through the exactly-once gate (identical to `rflow trigger`),
  `pause_workflow`/`resume_workflow` flip the Postgres kill-switch, and
  `retry_run` requeues a settled run. Every one of them lands in the durable
  journal and is executed (or not) by the running `rflow start` instance under
  the workflow's own permissions, simulation gates and relayer policies.
* **There is deliberately NO raw send/broadcast tool.** Transactions only ever
  originate from workflow definitions — an agent cannot construct and send an
  arbitrary transaction through rflow's relayers.
* **There is deliberately NO approve/reject tool either.** An agent can *see*
  pending [approval gates](/approvals) in the journal, but deciding a money
  gate stays with humans and the CLI.

### Tools

| Tool                 | Arguments                                                                     | What it does                                                                                             |
| -------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `validate_config`    | —                                                                             | Strict collect-all validation of `rflow.yaml`; every error and warning.                                  |
| `get_config_summary` | —                                                                             | Networks (name, chain id), workflows (trigger, paused), relayers (networks, reconciled onchain address). |
| `list_runs`          | `limit?`, `failed_only?`                                                      | Recent runs from the journal, newest first.                                                              |
| `get_run`            | `run_id`                                                                      | One run plus its full step journal: statuses, attempts, tx ids/hashes, outputs, errors.                  |
| `list_triggers`      | `limit?`                                                                      | Trigger keys fired per workflow — which exact events/ticks claimed runs.                                 |
| `get_cursors`        | —                                                                             | Indexer progress per workflow × network (anchor block, last processed block).                            |
| `trigger_workflow`   | `workflow`, `inputs?`                                                         | Claims a journaled manual run (`manual:<uuid>`), picked up by `rflow start`.                             |
| `pause_workflow`     | `workflow`                                                                    | Kill-switch: triggers keep matching, no new runs start.                                                  |
| `resume_workflow`    | `workflow`                                                                    | Resume a paused workflow.                                                                                |
| `retry_run`          | `run_id`                                                                      | Requeue a settled (`failed` \| `dead_letter` \| `succeeded`) run; resumes after its last completed step. |
| `get_health`         | —                                                                             | The `/health` payload: run counts per status, relayer count.                                             |
| `simulate_send`      | `network`, `contract_or_to`, `function?`, `args?`, `value?`, `data?`, `from?` | **Read-only** `eth_call` with decoded output — or the decoded revert reason.                             |

Every result is compact JSON. Tool failures (unknown workflow, bad uuid,
unreachable RPC) come back as in-band `isError` results with a precise message,
so agents can read the reason and correct course.

#### `simulate_send` in practice

`contract_or_to` is either a name from your `contracts:` registry (the ABI and
per-network address resolve automatically, `function` can be a bare name) or a
raw `0x` address (pass the full solidity signature, e.g.
`transfer(address,uint256)`). `value` accepts `1 ether` / `10 gwei` / wei
strings. A revert is a *successful* simulation with `"success": false` and the
decoded reason — exactly what the engine's pre-flight simulation would have
caught before a real send.

```json
{ "network": "ethereum", "contract_or_to": "USDC", "function": "transfer", "args": ["0x…", "1000000"], "from": "0x…relayer" }
```

→

```json
{ "success": false, "reverted": true, "reason": "execution reverted: ERC20: transfer amount exceeds balance" }
```


## Observability

rflow's single exposed port (`config.port`, default `3940`) carries everything
you need to watch a deployment: the health probe, a Prometheus `/metrics`
endpoint, a built-in run-trace viewer and the read-only JSON API behind it.

:::warning
The viewer and `/api/*` are **read-only**, and **unauthenticated by default** —
rflow's port is designed as a localhost / private-network operator tool. Don't
expose it to the public internet without turning on auth. To require a bearer
token on `/` and `/api/*` inside private infrastructure, set
[`config.server.auth.token`](/config/config#server--optional) (and
`config.server.cors` / `bind` as needed); `/health` stays open for probes and
`/metrics` follows auth unless `metrics_public`. The only state-changing routes
on the port are the webhook triggers you explicitly declare (each with its own
[HMAC `auth:`](/workflows/triggers/webhook) setting, independent of the bearer gate).
:::

### History explorer — `GET /`

Open `http://localhost:3940/` while `rflow start` is running. The run-trace
viewer has grown into a full **[history explorer](/operations/history-explorer)**
— a single dependency-free HTML/CSS/JS file embedded in the binary (no build
step, no external assets, works offline) with routed views:

* **Workflows overview** — every workflow with pause state, trigger kind, last
  run / success / failure, success & failure counts, runs waiting, median / p95
  duration, tx count, recent error kind and per-network cursor / head lag
* **Runs history** — the full filter/search set (workflow, status, trigger,
  network, contract, relayer, tx hash, block, run/step id, error kind, approval
  status, session, time range), shareable via the URL hash
* **Run detail** — the full **step timeline**: attempts, statuses, tx ids and
  hashes, redacted inputs/outputs, structured errors, durable-delay wake times,
  approval decisions, reorg linkage and the replay/test marker. A
  [`command`](/workflows/steps/command) step's parsed JSON output shows as
  `steps.<id>.output` (secrets redacted; the command's raw env is never journaled)
* **Transactions, Approvals, Waiting, Failures & dead-letters, Reorg responses,
  Replay/test sessions** — one focused view each

Untrusted run data (event args, errors, HTTP bodies) is escaped to text, never
rendered as HTML. When [auth](#json-api) is on the shell shows a login card and
sends a bearer on every API call. Full details: **[history explorer](/operations/history-explorer)**.

Each run also records the **`config_version`** of the boot that claimed it —
`rflow runs show <id>` prints it (next to the per-workflow `config_hash` resume
fence), and it is on every run in the JSON `/api`. That is the audit trail: a
run is always traceable to the exact config that produced it. See
[versioning & config plan](/operations/versioning-and-plan).

### Prometheus metrics — `GET /metrics`

Standard text exposition format; point a Prometheus scrape job at it:

```yaml
scrape_configs:
  - job_name: rflow
    static_configs:
      - targets: ["localhost:3940"]
```

| Metric                                                              | Type      | Labels                       | Meaning                                                                                                                                                                                   |
| ------------------------------------------------------------------- | --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rflow_runs_total`                                                  | counter   | `workflow`, `status`         | Runs settled, by terminal status (`succeeded` / `failed` / `dead_letter` / `skipped`).                                                                                                    |
| `rflow_run_duration_seconds`                                        | histogram | `workflow`                   | Run wall time from first start to settle.                                                                                                                                                 |
| `rflow_steps_total`                                                 | counter   | `workflow`, `step`, `status` | Step attempts settled in the journal (the `step` label is the journal step id; `foreach` iterations aggregate under one `<id>[]` series so fan-out size never becomes label cardinality). |
| `rflow_trigger_fires_total`                                         | counter   | `workflow`, `kind`           | Trigger fires that claimed a run — duplicate deliveries are excluded by the exactly-once gate.                                                                                            |
| `rflow_sends_total`                                                 | counter   | `workflow`, `status`         | Transaction lifecycle: `submitted` when handed to the relayer, then the terminal `succeeded` / `failed`.                                                                                  |
| `rflow_indexer_last_block`                                          | gauge     | `network`                    | Highest block any trigger cursor has processed.                                                                                                                                           |
| `rflow_waiting`                                                     | gauge     | `kind`                       | Runs parked waiting (`tx` / `delay` / `event` / `approval`), computed from the journal at scrape time.                                                                                    |
| `rflow_workflow_errors_total`                                       | counter   | `workflow`                   | Settled failures that fired at least one [`workflow_error` watcher](/operations/unattended-ops#the-workflow_error-meta-trigger), labelled by the FAILING workflow.                        |
| `rflow_liveness_breaches_total`                                     | counter   | `workflow`                   | [Liveness](/operations/unattended-ops#liveness--alert-when-a-workflow-goes-silent) breaches opened (one per breach, not per tick).                                                        |
| `rflow_liveness_breached`                                           | gauge     | `workflow`                   | 1 while a liveness breach is open, 0 once recovered.                                                                                                                                      |
| `rflow_indexer_stalled`                                             | gauge     | `network`                    | 1 while the chain head advances but every trigger cursor on the network is frozen past `monitoring.indexer_stall_after`.                                                                  |
| `rflow_process_start_time_seconds` / `rflow_process_uptime_seconds` | gauge     | —                            | Process basics.                                                                                                                                                                           |

Counters increment **at the journal choke points** — a series only moves after
the corresponding database transition committed, so `/metrics` never claims
something the journal doesn't show. Counters reset on restart (normal for
Prometheus; use `rate()`/`increase()`).

### JSON API

Stable, read-only endpoints — **unauthenticated by default**, or bearer-gated
when [`config.server.auth.token`](/config/config#server--optional) is set (`/health`
stays open for probes; `/hooks/*` keep their own HMAC):

| Endpoint                               | Returns                                                                                                                                                                                                                                                                                      |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /health`                          | `{status: "ok" \| "degraded", reasons: [...], project, workflows, runs: {<status>: n}, relayers}` — `degraded` (never an error status) when the database is unreachable, a [liveness breach](/operations/unattended-ops) is open or an indexer stall is detected; `reasons[]` explains each. |
| `GET /api/runs?limit=50[&failed=true]` | Recent runs, newest first (limit capped at 500).                                                                                                                                                                                                                                             |
| `GET /api/runs/:id`                    | One run with its full step journal and approvals.                                                                                                                                                                                                                                            |
| `GET /api/workflows`                   | Every workflow with pause state, trigger kind, cursors and today's run count.                                                                                                                                                                                                                |
| `GET /api/history/*`                   | The cursor-paginated, secret-redacted **[history explorer](/operations/history-explorer)** API: `runs`, `runs/:id/timeline`, `txs`, `approvals`, `waiting`, `reorgs`, `replays`, `workflows`, `export`.                                                                                      |

```bash
curl -s localhost:3940/api/runs?limit=5 | jq '.runs[].status'
```

### Watch mode — `rflow start --watch`

`--watch` hot-reloads `rflow.yaml` while rflow runs:

* edits are debounced (500ms) and **validated first** — an invalid save prints
  the errors red and the running config keeps running untouched
* a valid save drains the stack gracefully (in-flight runs journal their
  progress and resume, exactly like a restart) and boots the new config
  in-process.

Limitations: a reload restarts the embedded indexer/relayer engines in full,
and `.env` is **not** re-read — export changed environment variables and
restart for those.

### Preflight checks — `rflow validate --preflight`

Live connectivity checks before you deploy, printed as an ok/fail table
(exit code 1 on any failure):

* every network RPC is called with `eth_chainId` and compared against the
  declared `chain_id` (catches copy-pasted RPC urls pointing at the wrong
  chain)
* the database connection is opened and queried
* notification channels: Telegram gets a real `getMe`; Slack/Discord webhooks
  get a TCP reachability check by default — pass `--preflight-notify` to post
  an actual `[rflow preflight] connectivity check` message (webhooks cannot be
  verified without posting); PagerDuty/Opsgenie/Twilio get an API-host
  reachability check
* every [`command`](/workflows/steps/command) step: the executable resolves (on
  `PATH` or as a project-relative path with the executable bit), any local
  script argument exists, and a known interpreter reports its version (dynamic
  `${{ }}` invocations are reported as skipped)
* the signer/relayer bootstrap is deliberately **not** preflighted — creating
  wallets is a stateful operation `rflow start` owns.

Nothing in the output prints secrets: bot tokens, webhook URLs and connection
strings are redacted to their hosts.


## Reliability & exactly-once

"Exactly-once" is an easy claim and a hard contract. This page explains exactly what
rflow guarantees, how, and what it deliberately does not promise.

### The claim gate: one trigger occurrence, one run

Every trigger occurrence has a deterministic key — for events,
`chain_id:tx_hash:log_index` (plus the phase for
[`run_on: both`](/workflows/triggers/event#run_on--two-phase-firing) triggers);
for cron, the scheduled tick; for read/block triggers, the poll instant / block
number. Starting a run is an

```sql
INSERT ... ON CONFLICT DO NOTHING
```

against a `UNIQUE (workflow_name, trigger_key)` constraint in Postgres. Whoever
inserts the row owns the run; everyone else (a replayed block range, a reorged
duplicate, an overlapping backfill, a second delivery from the indexer) is a no-op.
There is no window where two runs exist for one occurrence, because the database is
the arbiter.

One deliberate exception: [webhook triggers](/workflows/triggers/webhook) without
`idempotency_key` are **at-least-once** — every accepted POST claims a fresh uuid
key, so a caller's retry is a new run. Webhooks have no *inherent* dedupe
identity; declare one with
[`trigger.webhook.idempotency_key`](/workflows/triggers/webhook#idempotency--dedupe-caller-retries)
(e.g. `${{ headers['x-idempotency-key'] }}` or `${{ body.event_id }}`) and a
duplicate POST within the TTL window creates **no** new run.

### The journal: state before side effects

Every run and every step is journaled in Postgres (`rflow.workflow_runs`,
`rflow.step_runs`). The invariant: **state is persisted before the side effect**. A
step's row exists before its HTTP call fires or its transaction is queued, and its
outcome (output, tx ids, error) is persisted when it settles.

So after a crash, recovery knows precisely where every run was:

* steps that completed are never re-executed — their journaled output feeds later
  steps' expressions (including each [`foreach`](/workflows#foreach--fan-a-step-out)
  iteration, which journals under its own `<id>[<i>]` row)
* a run parked in `waiting_delay` resumes its countdown against the persisted wake
  time
* a run parked in `waiting_tx` resumes polling the same transaction
* a run parked in `waiting_event` ([`wait_for`](/workflows/steps/wait-for)) keeps
  its persisted wait rows and timeout deadline
* a run parked in `waiting_approval` keeps its pending
  [approval](/approvals) — the gate is a database row, not process memory

### Sends: idempotency keys, not hope

The dangerous window is a send: rflow asks the relayer to queue a transaction, and
the process dies before the response lands. Did the tx get queued or not?

rflow journals a client-generated idempotency key **before** the request:

```
external_id = rflow:{run_id}:{step_id}:{attempt}
```

The embedded rrelayer stores it under a **unique index**. On recovery:

1. look up the external\_id — if the transaction exists, adopt it and keep waiting;
2. if it doesn't, re-send with the same external\_id — and if the original was
   actually in flight, the unique index makes the duplicate insert fail, so the
   retry collapses into a safe no-op.

Either way there is exactly one live transaction for that step attempt. This is why
the key must exist client-side before the request — rrelayer's own tx id only comes
back in the response, which is exactly what the crash may have eaten.

After queueing, the stable `tx_id` is adopted for status polling, and gas
bumping/rebroadcast (which change the tx hash, never the `tx_id`) are entirely
rrelayer's.

Compensation sends inside [`on_reorg:`](/reorgs#actionable-reorg-responses--on_reorg)
carry the same discipline under their own key shape —
`rflow-reorg:{run_id}:{fork_block}:{step_id}:{attempt}` — journaled in the
response's step journal (`rflow.reorg_step_runs`) before the relayer can see
the transaction.

### Approvals: the gate is a row

An [approval-gated send](/approvals) parks the run with a persisted approval row.
`rflow approve`/`reject` (or a timeout) settles that row; the executor picks the
decision up and continues. A crash while parked loses nothing — the pending
approval, its expiry, and the prepared transaction summary are all journaled,
and an approved send still goes through `recheck` + re-simulation before
broadcast. What is **not** guaranteed: with `on_timeout: proceed`, an unanswered
gate broadcasts — that is opt-in and
[`rflow validate` warns about it](/approvals#on_timeout-proceed--the-sharp-edge).

### Sagas: wait\_for guarantees

A [`wait_for`](/workflows/steps/wait-for) step persists its event conditions and
timeout deadline before parking, so sagas survive restarts. Every awaited
`(contract, event, network)` gets indexed: pairs no declared trigger watches
receive their own **wait-only subscription** at boot — it routes deliveries
only to the wait matcher (it can never create a run) and starts at the
**latest** block, catching future events while runs are parked. Resume depth is
the per-condition
[`confirmations:`](/workflows/steps/wait-for#confirmations--how-deep-before-the-wait-settles)
field — the default stays reorg-safe (a confirmed-depth delivery settles; a
head delivery only arms the wait until the network's depth is reached), and
`confirmations: 0` opts into head-speed resumes with the reorg risk validate
warns about. `wait_for` also parks per
[`foreach`](/workflows#foreach--fan-a-step-out) item and inside `finally:`
blocks, and `on_timeout: goto` crash-resume is **exact**: the jump decision is
journaled with the settle, so a restart lands on the same named step.

### Recovery semantics

On every boot, before triggers start flowing:

1. an advisory lock on `(database, project)` is taken — a second rflow process for
   the same project exits instead of double-running (or waits, if it is an
   [HA standby](/self-hosting#high-availability-leaderstandby))
2. incomplete runs (`queued` / `running` / `waiting_tx` / `waiting_delay` /
   `waiting_event` / `waiting_approval`) are scanned
3. `waiting_tx` steps reconcile against the relayer by external\_id
4. elapsed delays fire, in-flight steps resume from the journal
5. incomplete [`on_reorg:` responses](/reorgs#actionable-reorg-responses--on_reorg)
   (`rflow.reorg_runs` rows still `running`) resume through their own step
   journal — completed compensation steps never rerun, interrupted
   compensation sends reconcile by their idempotency key

Then live triggers resume from their persisted [cursors](/workflows/triggers/event#backfill-and-cursors).

An HA takeover runs exactly this path: the promoted standby recovers the dead
leader's in-flight work first, engines and triggers after — the same
exactly-once guarantees as any restart.

### Replays and tests never touch live state

[`rflow replay` and `rflow test`](/backtesting) run under **namespaced** workflow
names (`replay_<session>__<wf>` / `test_<uuid>__<wf>`) with prefixed trigger
keys, so a rehearsal can never collide with a live claim, a live executor never
picks up rehearsal runs, and the workflow's own run history stays clean. Dry-run
mode additionally stops every send before the relayer hand-off. Sessions are
reclaimable with [`rflow replay prune`](/backtesting#listing--pruning-sessions--rflow-replay-ls--prune),
which only ever deletes namespaced rows — never a live workflow.

### Failed runs: the dead letter queue

A run that fails terminally (with `on_failure: dead_letter`, the default) keeps its
full journal — every step's status, output, error, attempts and tx links — and lands
in the DLQ. `rflow runs list --failed` shows them; `rflow runs retry <id>` re-fires
one after you've fixed the cause. Repeated failures can
[trip a circuit breaker](/workflows#circuit_breaker) that pauses the workflow and
pages someone.

### Durable spend budgets survive restarts and races

Two workflow guards are Postgres-backed so they hold across a restart or an
[HA takeover](/self-hosting#high-availability-leaderstandby):

* **`rate_limit.durable: true`** persists the window in `rflow.rate_limit_buckets`
  as a fixed window claimed with one atomic `INSERT … ON CONFLICT` statement. A
  fresh process cannot reset a live window, and concurrent runs racing one bucket
  can never admit more than `max`. (The default `rate_limit` is in-process and
  resets on restart — see the caveat below.)
* **[`budgets:`](/workflows/budgets)** cap cumulative spend inside a rolling
  window. The cap is enforced by a **reservation** written *before* the send
  broadcasts, so racing runs cannot overshoot it.

A budget reservation follows the same money-path discipline as a send — persist
before the side effect, key by the send's idempotency `external_id`, let the
journal drive recovery:

1. **Reserve** — after every other pre-broadcast check, right before the relayer
   call, the send writes a durable `rflow.budget_reservations` row (one per
   asset) and atomically checks `(live reservations + settled spend) + amount ≤
   cap` under a per-`(budget, asset)` lock. Over the cap ⇒ the send fails
   `budget_exceeded`, any partial rows for the send are released, and **nothing
   broadcasts**.
2. **Settle or release by outcome** — a send that reaches the relayer flips its
   reservations to `spent`. A failure that *proves* the send never left the
   wallet (insufficient funds, a 429 rate-limit) flips them to `released`
   (refunded) immediately. An *ambiguous* failure (an rpc timeout, an unknown
   transport error) is instead left `reserved`: the transaction may have landed,
   so releasing it inline would drop it from the cap and let a concurrent send
   slip past — the reconcile settles it exactly-once. A send that is queued but
   then fails **on-chain** (reverted / dropped / expired) moved no value, so its
   already-`spent` reservation is refunded to `released` too — so a failed send
   never permanently consumes budget and its retry is not falsely refused.
3. **Reconcile** — a crash *between* reserve and settle, or an unresolved
   ambiguous failure, leaves live `reserved` rows. The recovery pass reconciles
   them by `external_id` exactly like a send: one that provably landed ⇒ `spent`
   (reclaiming even a prematurely `released` row), one that never landed ⇒
   `released`. The money is accounted at most once, and a queued value is
   treated as committed spend (conservative for a cap).

Because the reservation is keyed by `external_id`, a re-run of the same attempt
reserves the *same* row — a double reserve is one row, not double spend. See
[Budgets](/workflows/budgets) for the config surface and `rflow budgets ls`.

### What shutdown does — and does not — guarantee

On Ctrl-C / SIGTERM, rflow stops accepting new work, lets in-flight steps reach a
journal-consistent point, and shuts the engines down (the relayer drains its queues).
Combined with recovery, a `kill -9` at *any* point is safe in the sense that matters:
**no duplicated side effect** and no lost run.

What is **not** guaranteed:

* **At-most-once for non-idempotent HTTP.** A crash after an `http_call` fired but
  before its outcome was journaled means recovery re-executes that step. Sends are
  protected by idempotency keys; arbitrary HTTP cannot be. Use the
  [`hmac`](/workflows/steps/http-call#hmac-signing) signature plus an idempotency
  key of your own (e.g. `run.id`) on the receiving side if your endpoint is not
  idempotent. The same applies to a `notify:` in that crash window — you might get
  one alert twice. You will never get zero.
* **On-chain finality.** rflow's exactly-once is about *its own actions*. A reorg
  can still orphan the block your transaction landed in — see [Reorgs](/reorgs) —
  and can orphan the *triggering event* after a head-fired run already acted.
  `confirmations:` is the knob for that, and
  [`on_reorg:`](/reorgs#actionable-reorg-responses--on_reorg) is the response
  hook (itself exactly-once per `(run, fork)` and crash-resumable through its
  own step journal — see the reorgs page).
* **Missed cron ticks.** By default, a cron tick that comes due while the process
  is down is **skipped**. Opt into
  [`catch_up: true`](/workflows/triggers/cron#catch_up--missed-ticks) to replay
  missed slots on boot — capped at the newest 100. Transient claim errors while
  the process is *up* are retried within the tick's window (the dedupe key is the
  scheduled time, so retrying can never double-fire).
* **Per-instance windows.** [`rate_limit`](/workflows#rate_limit) windows are
  in-process **by default** — a restart or takeover starts them fresh. Set
  `rate_limit.durable: true` for a Postgres-backed fixed window that a restart
  cannot reset. (Trigger [`throttle:`](/workflows/triggers/event#throttle),
  [spend budgets](/workflows#budgets) and
  [circuit-breaker](/workflows#circuit_breaker) state are Postgres-backed and
  survive restarts.)

### Where state lives

Everything is in one Postgres (schemas `rflow`, `relayer`, `rindexer`). Back that
up and you can rebuild a machine from scratch: the YAML is the definition, Postgres
is the memory. Nothing else — no local files rflow can't regenerate (`.rflow/` is
generated runtime config, safe to delete).


## Reorgs & confirmations

Chains reorganize. rflow's stance: **you choose the trade-off per trigger, rflow
advises, and nothing is hidden.**

### The knob: confirmations

Every [event trigger](/workflows/triggers/event) takes:

```yaml
confirmations: 0           # fire at head (default)
confirmations: 12          # wait 12 blocks
confirmations: finalized   # wait for chain finality
```

* **`0` (default)** — fire the moment the event is seen. Fastest possible reaction;
  the event may later be orphaned by a reorg.
* **`N`** — fire once the event is N blocks deep. A reorg deeper than N can still
  orphan it, but the probability falls off fast.
* **`finalized`** — fire only once the chain's finality gadget has sealed the block.
  On Ethereum this is \~2 epochs (\~13 minutes); on L2s it follows the rollup's
  finality semantics. Orphaning a finalized block would mean a catastrophic chain
  failure.

### Per-chain guidance

`rflow validate` prints this advice (and never blocks on it):

| Chain                      | Suggested depth |
| -------------------------- | --------------- |
| ethereum                   | 20              |
| base / arbitrum / optimism | 24              |
| polygon                    | 200             |
| everything else            | 12              |

### Alert at head, pay at depth

The pattern that resolves most tension — in one workflow with
[`run_on: both`](/workflows/triggers/event#run_on--two-phase-firing):

```yaml
workflows:
  swap-watch:
    trigger:
      event:
        contract: AnyPool
        name: Swap
        network: ethereum
        confirmations: 20
        run_on: both          # fire at head AND at depth
    steps:
      - id: alert
        if: "${{ trigger.phase == 'unconfirmed' }}"
        notify: { channel: ops, message: "swap seen at head: ${{ trigger.tx_hash }}" }
      - id: mirror
        if: "${{ trigger.phase == 'confirmed' }}"
        send_transaction: { ... }
```

Each phase claims its own trigger key, so both fire exactly once for the same
swap — one instantly, one when it is safe to move money. (Two separate
workflows at different depths work identically, if you prefer the split.)

`rflow validate` warns specifically about the risky combination: a workflow that
**sends transactions from a head-fired event trigger**. A reorg can orphan the
triggering event *after* your transaction is already out — that transaction does not
un-happen.

### Actionable reorg responses — on\_reorg

When a reorg orphans an event a workflow **already ran on**, the workflow's
`on_reorg:` steps fire — the hook for alerts and compensations:

```yaml
workflows:
  fast-mirror:
    trigger:
      event: { contract: USDC, name: Transfer, network: ethereum, confirmations: 0 }
    steps:
      - id: mirror
        send_transaction: { ... }
    on_reorg:
      - id: warn
        notify:
          channel: ops
          message: >-
            REORG: the deposit behind run ${{ reorg.run_id }}
            (tx ${{ reorg.tx_hash }}, block ${{ reorg.block_number }}) was orphaned
            after we already mirrored it — fork at ${{ reorg.fork_block }}.
      - id: compensate
        send_transaction: { ... }   # e.g. claw the mirrored funds back
```

`on_reorg` steps see the full expression context (the original `trigger.*`
included) plus a `reorg` root:

| Path                                                   | Description                             |
| ------------------------------------------------------ | --------------------------------------- |
| `reorg.tx_hash`, `reorg.block_number`, `reorg.network` | The orphaned trigger occurrence         |
| `reorg.run_id`, `reorg.workflow`                       | The run that had already acted on it    |
| `reorg.fork_block`, `reorg.detection_block`            | The reverted range the indexer reported |

The semantics, stated precisely:

* **Exactly-once per `(run, fork_block)`, crash-resumable.** The response
  claim persists in `rflow.reorg_runs` **before** the first side effect, so a
  redelivered reorg notification can never double-fire a compensation. A
  deepening reorg detected in stages can't either: a re-detection whose
  `[fork_block, detection_block]` range overlaps an already-claimed
  handling's range is refused at the claim — one logical revert compensates
  once, no matter how many fork points the indexer reports for it. Only a
  distinct later reorg with a disjoint reverted range fires the response
  again. The
  response itself is a miniature journaled workflow: every step's row lands in
  `rflow.reorg_step_runs` **before** its side effect, and a crash mid-response
  leaves the claim `running` — the next boot's recovery pass resumes it
  through that journal. Completed steps never rerun, an interrupted delay
  wakes from its persisted wake time, and no step is silently dropped.
* **Compensation sends carry idempotency keys.** A `send_transaction` inside
  `on_reorg:` journals `rflow-reorg:{run_id}:{fork_block}:{step_id}:{attempt}`
  before the relayer can see the transaction — the same discipline as
  [normal sends](/reliability#sends-idempotency-keys-not-hope). On resume an
  interrupted send is reconciled by that key: adopted if it landed, re-sent
  under a fresh attempt only if it provably never reached the relayer, and
  left for the next recovery pass when the relayer is unreachable — never
  re-sent on ambiguity.
* **Kept simple by validation** — `approval:` gates, `foreach:`, and
  `wait_for:` are rejected inside `on_reorg:`; steps run sequentially with no
  retry policy, delays sleep inline (durably journaled), and sends are
  fire-and-forget: the journal records `sent` with the tx ids and the relayer
  keeps driving the transaction.
* **Never at the indexer's expense.** The reorg notification only persists
  the response claims inline; the compensation steps run on a detached task.
  A response sleeping out a long `delay:` never stalls event delivery, cursor
  advance, or further reorg detection on the network it fired from.
* **Inspectable.** `rflow runs show <source-run-id>` renders every reorg
  response fired for the run — fork block, status, and the per-step
  compensation trace — and `GET /api/runs/{id}` returns the same under
  `reorg_responses`. A response still shown `running` resumes on the next
  boot's recovery pass.
* **rflow never rolls back the original run.** `on_reorg:` is the signal that
  it acted on something the chain took back; what to do about it is yours to
  script.

### What the engines handle for you

The embedded rindexer detects reorgs and re-emits the canonical chain: rflow's
trigger dedupe (`chain_id:tx_hash:log_index`) means a re-emitted event that already
ran is skipped, and an event only present on the new branch fires normally. Cursors
track the canonical chain, so backfill/restart never double-processes a range.

### Accepted residual risks

Stated plainly, because no automation system can remove them:

1. **Head-fired actions on orphaned events.** With `confirmations: 0`, you accepted
   speed over certainty. If the triggering event is orphaned after your action ran,
   the action stands — `on_reorg:` lets you respond, it cannot undo.
2. **Reorgs deeper than N.** `confirmations: 12` does not protect against a
   13-block reorg. Pick depth by the value at stake; use `finalized` when it really
   matters.
3. **Your own transaction being reorged.** The relayer waits for the network's
   [`confirmations`](/config/networks#core-fields) depth before reporting CONFIRMED,
   and a send step with `wait_for: confirmed` inherits that —
   [`wait_for: confirmed(N)` / `finalized`](/workflows/steps/send-transaction#wait_for)
   go deeper when it matters. A reorg between inclusion and confirmation is handled
   (rrelayer keeps tracking/rebroadcasting); a reorg after you observed CONFIRMED is
   risk you tuned with that setting.
4. **Provider disagreement.** With multiple RPC urls, a lagging fallback can briefly
   disagree about head. Depth-based triggers absorb this; `confirmations: 0` may see
   events a beat earlier or later than another observer would.


## Self-hosting

rflow is one binary plus one Postgres. There is nothing else to run.

### Ports

rflow exposes **one** port — `config.port` (default 3940 in the scaffold), serving
health/status. The embedded engines are internal: rindexer's health server does not
bind, and rrelayer's API is off unless you opt in via
[`config.relayer_api`](/config/config#relayer_api--optional). Expose 3940 to your
monitoring; expose nothing else.

### Securing the port

By default the port is unauthenticated — fine on loopback or a private network,
not for shared clusters or anything internet-adjacent. Two ways to harden it,
usually combined:

**Bearer auth (built in).** Set
[`config.server`](/config/config#server--optional) to require
`Authorization: Bearer <token>` on the viewer `/` and `/api/*`:

```yaml
config:
  server:
    bind: 127.0.0.1:3940                       # keep the port on loopback behind a proxy
    auth:
      token: "${{ secrets.RFLOW_API_TOKEN }}"
    cors:
      origins: ["https://ops.example.com"]     # allow your dashboard's origin
```

`/health` stays open for k8s probes (`health_public` defaults true); `/metrics`
follows auth unless `metrics_public: true`. Mint extra tokens with
[`rflow token create`](/cli#rflow-token) and revoke leaked ones without a
restart. `/hooks/*` webhook routes keep their own [HMAC `auth:`](/workflows/triggers/webhook).

**Reverse proxy + TLS.** rflow serves plain HTTP; terminate TLS at a proxy
(nginx, Caddy, Traefik, or a cloud load balancer / k8s Ingress) in front of it.
Bind rflow to loopback (`bind: 127.0.0.1:3940`) so only the proxy can reach it,
and let the proxy handle certificates and (optionally) an extra auth layer. The
chart's `ingress` values wire this up on Kubernetes.

### DATABASE\_URL

All state lives in Postgres, configured once via
[`config.db_connection`](/config/config#db_connection--required) — conventionally:

```bash
DATABASE_URL=postgresql://postgres:rflow@localhost:5448/postgres
```

Point it at any Postgres 14+ (managed is fine). rflow applies its schema on boot,
takes a per-project advisory lock (so a stray second replica exits instead of
double-running), and the embedded engines get the same connection injected. Backing
up this database backs up everything.

### Docker compose

`rflow new` scaffolds a compose file for local Postgres. A full self-contained
deployment looks like:

```yaml
volumes:
  postgres_data:
    driver: local

services:
  postgresql:
    image: postgres:16
    shm_size: 1g
    restart: always
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - 5448:5432
    env_file:
      - .env

  rflow:
    image: ghcr.io/joshstevens19/rflow:latest
    restart: always
    depends_on:
      - postgresql
    command: ["start", "--path", "/app/project"]
    volumes:
      - ./:/app/project
    ports:
      - 3940:3940
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://postgres:rflow@postgresql:5432/postgres
```

Note the `DATABASE_URL` override: inside the compose network Postgres is
`postgresql:5432`, not `localhost:5448`.

### Helm

The repo ships a chart at `helm/rflow` (image `ghcr.io/joshstevens19/rflow`, service
port 3940). Your `rflow.yaml` goes in `values.yaml` as `rflowConfig`, mounted into
`projectPath`; secrets (DATABASE\_URL, RPC urls, tokens) come from env — wire them to
your secret manager.

```bash
helm install my-rflow ./helm/rflow \
  --set-file rflowConfig=./rflow.yaml \
  --set image.tag=latest
```

Run **one replica per project**: rflow is a stateful singleton by design, and the
advisory lock enforces it — a second replica will refuse to start against the same
project + database (unless it runs as a [standby](#high-availability-leaderstandby)).

To turn on [bearer auth](#securing-the-port), mount the token from a Secret with
the chart's `apiToken` values and reference it from `rflowConfig`:

```yaml
apiToken:
  enabled: true
  secretName: rflow-secrets     # kubectl create secret generic rflow-secrets --from-literal=rflow-api-token=...
  secretKey: rflow-api-token    # injected as RFLOW_API_TOKEN
```

```yaml
# in rflowConfig:
config:
  server:
    auth:
      token: "${{ secrets.RFLOW_API_TOKEN }}"
secrets:
  RFLOW_API_TOKEN: ${RFLOW_API_TOKEN}
```

### High availability (leader/standby)

For failover, run extra replicas as **standbys**:

```bash
rflow start --standby       # or in rflow.yaml:
```

```yaml
config:
  ha:
    standby: true           # this instance waits instead of exiting on LockHeld
    takeover_poll: 5s       # how often it re-probes the lock (default 5s)
```

How it works:

* exactly one **leader** executes; it holds the per-project Postgres advisory lock
  for the lifetime of its session
* standbys validate, connect and then **park before the lock**, logging
  `standby: waiting for leadership` while they poll
* when the leader dies — clean shutdown, `kill -9`, node loss, network partition
  dropping its database session — Postgres frees the session-scoped lock and a
  standby wins it within one poll interval
* the promoted standby runs the **normal boot continuation**: the journal recovery
  pass first (resuming/adopting whatever the dead leader left in flight), engines
  and triggers after — the same exactly-once path as any restart

**Fencing**: the advisory lock IS the fence — two executors can never run the same
project simultaneously, but only because every instance points
`config.db_connection` at the **same Postgres**. Separate databases means separate
locks and two live executors: don't. The leader also watches its own lock session:
if that dedicated database session dies while the process is still alive (a
Postgres restart, a load balancer dropping the idle connection), the server has
already freed the lock — so the leader **exits immediately** rather than keep
executing unfenced, and the standby's takeover boot resumes everything from the
journal.

`rflow status` shows the leadership state (leader running / no leader, via a lock
probe).

### Graceful shutdown

Send SIGTERM (docker stop / kubernetes termination do this) and rflow stops
accepting triggers, brings in-flight steps to a journal-consistent point, drains the
relayer, and exits. A hard kill is also safe — see
[Reliability](/reliability#what-shutdown-does--and-does-not--guarantee) — recovery
resumes from the journal on next boot.

### Sizing

rflow is a single tokio process doing in-process function calls; CPU needs are
modest (the helm defaults request `100m`/`128Mi`). What actually matters:

* **RPC quality** — latency to your provider dominates end-to-end reaction time;
  a fast HTTP provider and a tight `block_poll_frequency` matter most (`ws:`
  is parsed but not wired to the engines yet)
* **Postgres** — every run/step is journaled; give it real storage, and back it up
* **Backfill** — historical `start_block: earliest` runs are indexer-bound; more
  `max_block_range`/CU budget helps


## Budgets — durable spend caps

`permissions.max_value_per_tx` caps **one** send. A **budget** caps
**cumulative** spend inside a rolling window across *every* workflow, run and
send that attaches it — the blast-radius cap when something upstream misbehaves
(a bad price, a runaway loop, a compromised trigger). Budgets are durable and
reservation-based: racing runs cannot overshoot a cap, and a restart cannot
reset one.

```yaml
budgets:
  treasury-daily:
    window: 24h
    max_native_value: 10 ether        # cap on cumulative native value in the window
    max_token_value:
      USDC: "1000000"                 # raw token units (matches contracts.USDC)
    scope:
      relayers: [treasury]            # only sends from these relayers charge it
      networks: [ethereum]            # only sends on these networks charge it

workflows:
  sweep:
    budgets: [treasury-daily]         # this workflow's sends charge the budget
```

### Config surface

Top-level `budgets:` is a map of `name → budget`. Each budget:

| key                | required         | meaning                                                                                                                                        |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `window`           | yes              | The rolling window (`24h`, `1h`, `30m`, …). Consumption is summed over sends whose reservation is younger than the window.                     |
| `max_native_value` | one cap required | Cap on cumulative **native** value. A wei amount or a unit literal (`10 ether`, `500 gwei`).                                                   |
| `max_token_value`  | one cap required | Map of `SYMBOL → raw amount`. Raw units in the token's own decimals — there is no fiat oracle.                                                 |
| `max_gas_spend`    |                  | Circuit-breaker cap on cumulative **recorded gas spend** (a wei amount or unit literal). See [below](#max_gas_spend--the-gas-circuit-breaker). |
| `scope.relayers`   |                  | Only sends from these relayers charge the budget (absent = every relayer).                                                                     |
| `scope.networks`   |                  | Only sends on these networks charge the budget (absent = every network).                                                                       |

A workflow opts in with `workflows.<wf>.budgets: [name, ...]`. A send charges a
budget only when the workflow attaches it **and** the send's relayer/network
match the budget's `scope`.

### How a send charges a budget

Before a send broadcasts — after every other check (permissions, simulation,
gas cap, recheck, approval), right before the relayer call — it **reserves** its
value against each attached, in-scope budget:

1. **Native value first.** The send's native `value` charges `max_native_value`.
2. **One ERC20 amount second.** See the decoding rules below.

The reservation is checked atomically against
`(live reservations + settled spend in the window) + amount ≤ cap`. If it would
exceed the cap the send fails [`budget_exceeded`](/workflows/steps/send-transaction),
the run [dead-letters](/reliability#failed-runs-the-dead-letter-queue) per its
`on_failure`, and **nothing broadcasts** — the relayer never sees it. Because the check and insert happen
under a per-`(budget, asset)` lock, concurrent runs racing the same budget can
never collectively exceed the cap.

The reservation is a durable row keyed by the send's idempotency `external_id`,
so it is exactly-once and crash-safe. Its lifecycle — reserve → `spent` on a
successful hand-off, `released` (refunded) on a *proven* failure or a terminal
on-chain revert/drop/expire (an *ambiguous* failure is left `reserved` for the
reconcile, since the tx may have landed), and recovery reconcile by
`external_id` after a crash — is covered in
[Reliability → Durable spend budgets](/reliability#durable-spend-budgets-survive-restarts-and-races).

#### ERC20 charging is second-class

An ERC20 amount is decoded and charged **only** when a single-call send is an
unambiguous `transfer` / `transferFrom` / `approve` whose contract **registry
name equals the token symbol** in `max_token_value` — e.g. `contracts.USDC` ↔
`max_token_value.USDC`. Everything else is **native-only**:

* **Multicall batches** are native-only (the batch's aggregate value still
  charges `max_native_value`).
* Any other function, or a `contract:` whose name is not a budget symbol, is
  native-only.
* A `max_token_value` symbol with no matching `contracts.<symbol>` is accepted
  but can never be charged — `rflow validate` warns so the gap is visible.

Token amounts are raw units in the token's own decimals. There is no fiat
oracle and no cross-asset conversion in the first version.

### `max_gas_spend` — the gas circuit breaker

Value caps guard what a send *transfers*; `max_gas_spend` guards what rflow
*pays in gas*. It is checked against the receipt-derived
[spend ledger](/operations/spend-tracking) (`rflow.native_spend`,
`gas_used × effective_gas_price` of every settled send) before each in-scope
send: once the **recorded** gas spend inside the budget's scope and window has
reached the cap, further sends fail `budget_exceeded` before any broadcast.

```yaml
budgets:
  solver-gas:
    window: 24h
    max_gas_spend: 1 ether       # wei literal, validated like max_native_value
    scope:
      relayers: [solver]
```

Unlike the value caps this is **not a reservation** — actual gas is only known
at the receipt, and pre-send estimates are deliberately excluded (nodes over-
and under-estimate, prices move between estimate and inclusion, L2 fee
components are invisible pre-send). It is a **circuit breaker over settled
truth, not a precise limiter**: sends already in flight when the cap trips can
overshoot it by their own gas before their receipts land in the ledger, so
size the cap with headroom. Recorded spend is inspectable with
[`rflow spend`](/operations/spend-tracking).

### Inspecting consumption — `rflow budgets ls`

```bash
rflow budgets ls
# budget          asset   cap                   consumed  reserved  remaining  window
# treasury-daily  native  10000000000000000000  3000...   1000...   6000...    24h
# treasury-daily  USDC    1000000               250000    0         750000     24h
```

* `reserved` — in-flight sends not yet settled.
* `consumed` — `reserved + spent` (settled), i.e. what counts against the cap now.
* `remaining` — `cap − consumed`.

All amounts are raw units (wei for native, the token's own decimals for ERC20)
inside the budget's current rolling window. `rflow runs show <id>` and
`GET /api/runs/{id}` list the budgets each run's sends charged, with amounts and
status.

### Validation

`rflow validate` (and `rflow doctor`) check budgets statically:

* every name in a workflow's `budgets: [...]` resolves to a defined budget;
* every `scope.relayers` / `scope.networks` entry names a declared relayer /
  network;
* `window`, `max_native_value` and each `max_token_value` amount parse;
* a `max_token_value` symbol with no matching contract **warns** (free-form
  symbols are allowed but never charged).

### How budgets compose

* **`permissions.max_value_per_tx`** caps one send; a budget caps cumulative
  spend across many. Use both — a per-tx ceiling *and* a rolling blast-radius cap.
* **`rate_limit`** caps run *starts*; a budget caps *value*. A workflow can have
  both. Set [`rate_limit.durable: true`](/workflows#rate_limit) for a window that,
  like budgets, survives a restart.


## Expressions

One `${{ ... }}` language everywhere: conditions (`where` / `if` / `assert` /
`retry_if` / `condition` / `recheck`) and values (args, messages, urls, bodies)
all render through the same engine. It is GitHub-Actions-shaped on the outside and
[minijinja](https://github.com/mitsuhiko/minijinja)-powered underneath, tuned for
EVM work: strict U256 math, case-insensitive addresses, and strict-undefined
behavior (a typo'd key is an error, never a silent `false`).

```yaml
where: "${{ trigger.args.sender in lists.watched_traders and trigger.args.amount0 > wei('1', 18) }}"
message: "mirrored ${{ format_units(trigger.args.value, 6) }} USDC — ${{ steps.mirror.tx.hash }}"
```

### Contexts

| Root                  | Contents                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger`             | The firing occurrence. Events: `trigger.args.<name>`, `tx_hash`, `log_index`, `block_number`, `block_hash`, `address`, `network`, `chain_id`, `topics`, [`phase`](/workflows/triggers/event#run_on--two-phase-firing). Other triggers document their own shapes: [cron](/workflows/triggers/cron) · [webhook](/workflows/triggers/webhook#the-trigger-context) · [read](/workflows/triggers/read#the-trigger-context) · [query](/workflows/triggers/query#the-trigger-context) · [block](/workflows/triggers/block#the-trigger-context) |
| `trigger.failed`      | Inside a [`workflow_error`](/operations/unattended-ops#the-workflow_error-meta-trigger)-triggered workflow: `.workflow`, `.run_id`, `.trigger_key`, `.status`, `.step_id`, `.attempt`, `.error.kind`, `.error.message` of the failed source run                                                                                                                                                                                                                                                                                         |
| `events.<id>`         | Inside a [composite (`all`/`any`)](/workflows/triggers/composite)-triggered workflow — each correlated event by its list id: `events.<id>.args.<name>`, `.tx_hash`, `.block_number`, `.address`, … A composite `where:` also sees `events.<earlier-id>.*` at match time                                                                                                                                                                                                                                                                 |
| `steps.<id>`          | Any settled prior step: `.output`, `.status`, `.error`, `.tx` (`.tx.hash`), `.tx_id` (stable across gas bumps), `.receipt`                                                                                                                                                                                                                                                                                                                                                                                                              |
| `output`              | Inside `read.assert:` / [`query.assert:`](/workflows/steps/query#assert--the-gate) and a read/query trigger's `condition:` — the value being gated (alias `result`); query `NUMERIC` results compare as exact numbers                                                                                                                                                                                                                                                                                                                   |
| `sim`                 | Inside [`assert_sim:`](/workflows/steps/send-transaction#assert_sim--gates-over-the-simulation) only — `sim.ok`, `sim.gas_used`, `sim.return_data`                                                                                                                                                                                                                                                                                                                                                                                      |
| `item` / `item_index` | Inside a [`foreach:`](/workflows#foreach--fan-a-step-out) iteration — the current element (or batch) and its index                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `matrix`              | Inside a [matrix](/workflows#strategymatrix--one-definition-many-runs) combination run — `matrix.<axis>`                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `state`               | The Postgres-backed key/value store — see [state\_set](/workflows/steps/state-and-lists#state_set). Guard first reads with `is defined`                                                                                                                                                                                                                                                                                                                                                                                                 |
| `previous_run`        | The workflow's last **succeeded** run: `.id`, `.status`, `.steps.<id>.output/.status` — undefined on the first run, see [previous\_run](/workflows/steps/state-and-lists#previous_run--compare-against-last-time)                                                                                                                                                                                                                                                                                                                       |
| `reorg`               | Inside [`on_reorg:`](/reorgs#actionable-reorg-responses--on_reorg) steps only — `tx_hash`, `block_number`, `network`, `run_id`, `workflow`, `fork_block`, `detection_block`                                                                                                                                                                                                                                                                                                                                                             |
| `contracts.<name>`    | `.address` of registry contracts (on the relevant network)                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `relayers.<name>`     | `.address` of named relayers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `constants`           | Your [`constants:`](/config/constants-secrets-lists#constants)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `secrets`             | Your [`secrets:`](/config/constants-secrets-lists#secrets) — log-redacted                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `lists.<name>`        | Watchlist members (seed ∪ runtime ∪ source), for the `in` operator                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `run`                 | `run.id`, `run.workflow` — plus `run.status` inside [`finally:`](/workflows#finally--always-run-steps) steps                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `error`               | Inside `retry_if:` only — `error.kind`, `error.message`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `inputs`              | Manual trigger inputs — `rflow trigger <wf> --input k=v` exposes each pair as `inputs.<k>`                                                                                                                                                                                                                                                                                                                                                                                                                                              |

`rflow validate` knows which roots are legal where — a `reorg.*` reference in a
normal step, or `sim.*` outside `assert_sim:`, is a validation error, not a
runtime surprise.

### Operators

Boolean logic uses **words, not symbols**:

| Use   | Not        |
| ----- | ---------- |
| `and` | ~~`&&`~~   |
| `or`  | ~~`\|\|`~~ |
| `not` | ~~`!`~~    |

:::warning
`&&` and `||` are **not supported** and will fail at validation. Write
`${{ a and b }}`, `${{ a or b }}`, `${{ not a }}`.
:::

Everything else is as expected: `== != < <= > >=`, arithmetic `+ - * / %`,
membership `x in list`, string concat `~`, definedness tests
(`x is defined` / `x is not defined` — `and`/`or` short-circuit, so guards
work), and inline conditionals in Python style:

```yaml
args: ["${{ steps.gate.output if steps.gate.output < trigger.args.amount0 else trigger.args.amount0 }}"]
```

(there is no C-style `cond ? a : b` ternary).

### Functions

| Function                            | Description                                                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `wei(v, decimals)`                  | Parse a decimal amount into its integer representation: `wei('1.5', 18)` → `1500000000000000000`. Alias of `parse_units` |
| `parse_units(v, decimals)`          | Same contract as `wei`                                                                                                   |
| `format_units(v, decimals)`         | The inverse — integer → decimal string, for messages                                                                     |
| `mul_div(a, b, d)`                  | `a * b / d` computed at 512-bit width — scale amounts without overflow: `mul_div(amount, constants.scale_bps, 10000)`    |
| `min(a, b, ...)` / `max(a, b, ...)` | Across native ints and U256s                                                                                             |
| `checksum(addr)`                    | EIP-55 checksummed form of an address                                                                                    |
| `lower(s)`                          | Lowercase a string                                                                                                       |
| `keccak256(s)`                      | Keccak-256 hash, `0x`-hex                                                                                                |
| `abi_encode(sig, args...)`          | ABI-encode values, `0x`-hex                                                                                              |
| `now()`                             | Current unix timestamp (seconds)                                                                                         |
| `duration('5m')`                    | Parse a duration string to seconds                                                                                       |
| `from_json(s)`                      | Parse a JSON string into a value                                                                                         |

All functions are strict: bad inputs raise template errors that route to failure
handling — nothing degrades to floats or silent zeros.

### U256 math is strict

Token amounts never touch floats:

* `uint256` values that fit in a native integer stay native — every operator works,
  and the math is **checked** (overflow raises, never wraps)
* larger values stay exact as U256 objects — comparisons (`> < ==`) work directly;
  arithmetic on them is a loud error telling you to use `mul_div`/`wei` (which
  compute wide)
* decimal strings from event payloads coerce transparently in comparisons against
  `wei(...)` results

```yaml
where: "${{ trigger.args.value > wei('100000', 6) }}"          # exact
args: ["${{ mul_div(trigger.args.value, 9950, 10000) }}"]      # 0.5% haircut, no overflow
message: "${{ format_units(trigger.args.value, 6) }} USDC"     # human-readable out
```

### Addresses are case-insensitive

Every string in the context that looks like an address (`0x` + 40 hex) is normalized,
so equality and list membership behave regardless of casing:

```yaml
where: "${{ trigger.args.to == relayers.payout.address }}"        # just works
where: "${{ trigger.args.sender in lists.watched_traders }}"      # any casing in the seed
```

For literals you write yourself, either casing works when compared against context
values; use `lower('0xAbC...')` or `checksum(...)` if you need a canonical form in
output.

### Conditions are strictly boolean

A `where` / `if` / `assert` / `retry_if` must evaluate to a real boolean. A non-bool
result, an unknown key, or any evaluation error is a **typed error routed to failure
handling** — never a silent `false`. You find out about typos on the first event,
not never.

`rflow validate` additionally checks expressions statically: unknown context roots
and references to steps/contracts/lists that don't exist are caught before boot.

### Values keep their types

When a field is exactly one expression (`args: ["${{ trigger.args.value }}"]`), the
value keeps its type — numbers stay numbers, U256s stay exact. Mixed text
(`"amount: ${{ x }}"`) renders to a string. Output is single-pass and never
re-parsed, so event data can't inject expressions.


## Workflows

A workflow is *when this happens, do these things, in order*. Each entry under
`workflows:` (keyed by name) has one trigger and a list of steps.

```yaml
workflows:
  copy-trade:
    paused: false
    permissions:
      relayers: [payout]
      max_value_per_tx: 1 ether
    concurrency:
      group: "${{ trigger.args.sender }}"
      on_conflict: queue
    rate_limit: { max: 10, per: 1h }
    circuit_breaker:
      max_failures: 3
      window: 10m
      on_trip: [pause, notify: { channel: ops }]
    trigger:
      event: { contract: AnyPool, name: Swap, network: ethereum }
    steps:
      - id: gate
        read: { ... }
      - id: mirror
        send_transaction: { ... }
        retry: { max_attempts: 3 }
      - id: report
        notify: { ... }
    finally:
      - id: audit
        http_call: { url: "${AUDIT_URL}", body: { run: "${{ run.id }}", status: "${{ run.status }}" } }
    on_failure: dead_letter
```

### Fields

| Field             | Default       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger`         | ✅ required    | Exactly one of [`event`](/workflows/triggers/event) \| [`cron`](/workflows/triggers/cron) \| [`interval`](/workflows/triggers/interval) \| [`webhook`](/workflows/triggers/webhook) \| [`read`](/workflows/triggers/read) \| [`query`](/workflows/triggers/query) \| [`block`](/workflows/triggers/block) \| [`stream`](/workflows/triggers/stream) \| [`all` / `any`](/workflows/triggers/composite) \| [`workflow_error`](/operations/unattended-ops#the-workflow_error-meta-trigger) |
| `steps`           | ✅ required    | Strictly sequential list — see below                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `paused`          | `false`       | Kill-switch. Runtime pause state (`rflow workflow pause`) lives in Postgres and overrides this                                                                                                                                                                                                                                                                                                                                                                                          |
| `liveness`        |               | Alert when the workflow claims no run for `max_silence` — see [Unattended ops](/operations/unattended-ops#liveness--alert-when-a-workflow-goes-silent)                                                                                                                                                                                                                                                                                                                                  |
| `permissions`     |               | Guard rails — see below                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `concurrency`     |               | Per-entity serialization + conflict policy — see below                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `rate_limit`      |               | Cap run starts per window (add `durable: true` for a restart-proof window) — see below                                                                                                                                                                                                                                                                                                                                                                                                  |
| `budgets`         |               | Names of top-level [`budgets:`](#budgets) this workflow's sends charge — see below                                                                                                                                                                                                                                                                                                                                                                                                      |
| `circuit_breaker` |               | Trip the workflow open after repeated failures — see below                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `strategy`        |               | Matrix expansion — see below                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `finally`         |               | Steps that always run after the run settles — see below                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `on_reorg`        |               | Steps that run when a reorg orphans this workflow's trigger — see [Reorgs](/reorgs#actionable-reorg-responses--on_reorg)                                                                                                                                                                                                                                                                                                                                                                |
| `on_failure`      | `dead_letter` | What happens to a failed run: `dead_letter` (Postgres DLQ + `rflow runs retry`) \| `drop` \| `halt`                                                                                                                                                                                                                                                                                                                                                                                     |

### Steps run in order

A step list is strictly sequential: 1 → 2 → 3. There is no DAG and no `needs:` —
the default mental model stays simple. Any prior step's results are addressable from
any later step: `${{ steps.gate.output }}`, `${{ steps.mirror.tx.hash }}`,
`${{ steps.mirror.status }}`.

Every step shares these common fields around its action:

| Field                         | Description                                                                               |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| `id`                          | Step id — addressable as `steps.<id>.*`. Optional for steps nothing refers back to        |
| `if`                          | Condition gating the step, e.g. `"${{ steps.gate.output > 0 }}"`. False → step is skipped |
| `foreach`                     | Fan the action out over a collection — see below                                          |
| `max_parallel` / `batch_size` | foreach tuning — see below                                                                |
| `retry`                       | Retry policy — see below                                                                  |
| `timeout`                     | Overall step timeout, e.g. `5m`                                                           |

The action itself is exactly one of:
[`send_transaction`](/workflows/steps/send-transaction) ·
[`read`](/workflows/steps/read) · [`query`](/workflows/steps/query) ·
[`command`](/workflows/steps/command) ·
[`http_call`](/workflows/steps/http-call) ·
[`notify`](/workflows/steps/notify) · [`delay`](/workflows/steps/delay) ·
[`wait_for`](/workflows/steps/wait-for) ·
[`choose`](/workflows/steps/choose) ·
[`state_set` / `list_add` / `list_remove`](/workflows/steps/state-and-lists).

### foreach — fan a step out

Run one step's action once per element of a collection expression:

```yaml
- id: payout
  foreach: "${{ from_json(steps.plan.output.body).recipients }}"
  max_parallel: 4          # default 1 (strictly sequential)
  batch_size: 10           # optional — item becomes the batch (an array)
  send_transaction:
    network: ethereum
    relayer: payout
    contract: USDC
    function: "transfer(address,uint256)"
    args: ["${{ item.address }}", "${{ item.amount }}"]
```

* Each iteration sees `${{ item }}` and `${{ item_index }}`; `if:` is evaluated
  **per iteration**.
* Each iteration journals under `<id>[<i>]` with its own idempotency key —
  sends stay exactly-once **per element**, and a crash resumes exactly the
  interrupted iterations (settled ones never re-run).
* The parent step settles last with `output` = the array of iteration outputs
  (skipped iterations contribute `null`).
* Failure policy: any iteration failing after its retries fails the whole step.
  With `max_parallel: 1` later items never start; with parallelism, in-flight
  iterations drain (never cancelled mid-send) but nothing new starts.
* [`wait_for`](/workflows/steps/wait-for) runs inside a foreach: each item
  parks its own `<id>[<i>]` wait rows and resumes exactly once
  ([placement rules](/workflows/steps/wait-for#placement)); `on_timeout: goto`
  is rejected here.

### strategy.matrix — one definition, many runs

```yaml
strategy:
  matrix:
    network: [ethereum, base, arbitrum]
  fail_fast: false        # stop remaining combos after the first failure
  max_parallel: 2         # cap combos running concurrently
```

Each trigger fire expands into **one run per combination**; steps read the
combination as `${{ matrix.network }}`. Every combination extends the trigger
key (`...:matrix:network=base`), so each is individually exactly-once — a crash
mid-expansion resumes idempotently.

### finally — always-run steps

`finally:` steps run after the run settles, **success or failure** — audit
trails, lock releases, "run finished" pings. They see the full context plus
`run.status` (the terminal status). A `finally:` failure is logged and
journaled but does not change the run's outcome.
[`wait_for`](/workflows/steps/wait-for) may park inside `finally:` (the run's
terminal status never changes while it waits —
[placement rules](/workflows/steps/wait-for#placement)); `on_timeout: goto` is
rejected here.

### permissions

```yaml
permissions:
  relayers: [payout]          # only these relayers may be used by this workflow
  max_value_per_tx: 1 ether   # cap on native value per send
```

### concurrency

```yaml
concurrency:
  group: "${{ trigger.args.sender }}"   # expression → serialization key
  on_conflict: queue                    # queue | skip | cancel_in_progress | replace
```

Runs whose `group` expression evaluates to the same key are serialized —
per-trader, per-vault, per-anything. Runs in different groups execute concurrently
up to [`config.max_concurrent_runs`](/config/config#max_concurrent_runs--optional).

`on_conflict` decides what a new run does when its group's lane is busy:

| Mode                 | Behaviour                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `queue` *(default)*  | Wait — FIFO within the group                                                                                          |
| `skip`               | The newcomer settles as `skipped` (terminal, journaled with the in-flight run's id)                                   |
| `cancel_in_progress` | The in-flight run is superseded **at its next safe point** — between steps, never mid-send — then the newcomer starts |
| `replace`            | Alias of `cancel_in_progress` today                                                                                   |

Superseded runs are deliberate cancellations — they never count as
circuit-breaker failures.

### rate\_limit

```yaml
rate_limit: { max: 10, per: 1h }
rate_limit: { max: 10, per: 1h, durable: true }   # restart-proof
```

At most `max` run **starts** per `per` window. Claims beyond the limit stay
queued (never dropped) and start when the window has room — combined with the
exactly-once gate, nothing is lost, just deferred.

By default the window is **in-process, per rflow instance** (a sliding window):
a restart, or an
[HA takeover](/self-hosting#high-availability-leaderstandby), starts with a
fresh window, so a burst right after a restart can exceed the configured rate.

Set **`durable: true`** to persist the window in Postgres
(`rflow.rate_limit_buckets`). The durable limiter is a **fixed window** claimed
with one atomic `INSERT … ON CONFLICT` statement: the first run in a window
anchors it, the window releases `per` later, and concurrent runs racing the same
bucket can never exceed `max`. A restart or takeover then **cannot** reset a
live window.

### budgets

Top-level `budgets:` cap **cumulative spend** inside a rolling window across
*every* workflow, run and send that attaches them — the blast-radius cap when
something upstream goes wrong.

```yaml
budgets:
  treasury-daily:
    window: 24h
    max_native_value: 10 ether      # cap on cumulative native value in the window
    max_token_value:
      USDC: "1000000"               # raw token units (matches contracts.USDC)
    scope:
      relayers: [treasury]          # only sends from these relayers charge it
      networks: [ethereum]          # only sends on these networks charge it

workflows:
  sweep:
    budgets: [treasury-daily]       # this workflow's sends charge the budget
```

Before a send broadcasts (after every other check, right before the relayer
call) it **reserves** its native value first, then a decodable ERC20 amount,
against each attached in-scope budget. If a reservation would exceed the cap the
send fails `budget_exceeded` and **nothing broadcasts** — racing runs cannot
overshoot the budget. The reservation is a durable row keyed by the send's
idempotency key, so it is exactly-once and crash-safe: a queued send settles as
`spent`, a failed send is released (refunded), and the recovery pass reconciles
orphaned reservations by the same key. Inspect live consumption with
[`rflow budgets ls`](/cli#rflow-budgets-ls).

See **[Budgets](/workflows/budgets)** for the full config surface, the ERC20
second-class charging rules, validation and how budgets compose with
`permissions.max_value_per_tx`.

### circuit\_breaker

```yaml
circuit_breaker:
  max_failures: 3
  window: 10m
  on_trip: [pause, notify: { channel: ops }]
```

After `max_failures` terminally failed runs inside `window`, the circuit
**trips**: `pause` pauses the workflow, `notify:` alerts a channel (pagerduty
channels receive it as `critical`). State machine, persisted in Postgres
(`rflow.circuit_state` — restarts do not forget a tripped circuit):

* **closed** → failures are counted in the window
* **open** → after a full window with no new failures, the workflow is
  un-paused and one probe run is allowed through (**half\_open**). Only the
  breaker's own pause is lifted: an operator's `rflow workflow pause` placed
  during the incident survives the auto-reset (resume it yourself when ready)
* **half\_open** → exactly ONE run at a time is admitted for the whole
  workflow — `concurrency.group` lanes and matrix combos wait behind the
  probe. Probe fails: re-trips immediately; probe succeeds: closes and clears
  the window

### Retries and the failure taxonomy

Every step failure carries a `kind` from a fixed taxonomy:

```
simulation_failed | reverted | insufficient_funds | rpc_timeout | rate_limited |
nonce_conflict | timeout | expired | dropped | data_unavailable | assert_failed |
gas_cap_exceeded
```

`retry:` applies to **pre-queue and off-chain failures only** — `rpc_timeout`,
`rate_limited`, `data_unavailable`, `gas_cap_exceeded`. A reverted or failed
onchain transaction is a step failure and is **never blind-retried**; once a tx
is queued, gas bumping and rebroadcast are the embedded relayer's job.

```yaml
retry:
  max_attempts: 3
  retry_if: "${{ error.kind in ['rpc_timeout', 'rate_limited'] }}"   # optional
  backoff: 10s                                                       # optional
```

`retry_if` evaluates against the `error` context (`error.kind`, `error.message`).
Without it, any retryable kind retries up to `max_attempts`.

### Failure handling

When a step fails terminally (non-retryable kind, or attempts exhausted), the run
fails and `on_failure` decides its fate:

* `dead_letter` *(default)* — the run lands in the Postgres DLQ with its full journal;
  inspect with `rflow runs list --failed`, re-fire with `rflow runs retry <id>`
* `drop` — log and forget
* `halt` — pause the workflow itself; no further runs until resumed

`finally:` steps still run on every path.


## Block trigger

Fire a workflow every N blocks on a network — keeper duties, per-block checks,
periodic onchain maintenance that should track chain time rather than wall time.

```yaml
workflows:
  keeper:
    trigger:
      block:
        every: 10            # every 10th block
        network: ethereum
    steps:
      - id: upkeep
        read:
          contract: Keeper
          network: ethereum
          function: "checkUpkeep()"
          assert: "${{ output }}"
      - id: perform
        send_transaction:
          network: ethereum
          relayer: keeper
          contract: Keeper
          function: "performUpkeep()"
```

| Field     | Required | Description                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| `every`   | ✅        | Fire every N blocks (`>= 1`, validated). `1` fires every block |
| `network` | ✅        | A declared [network](/config/networks)                         |

### The trigger context

| Path                        | Description          |
| --------------------------- | -------------------- |
| `trigger.args.block_number` | The block that fired |
| `trigger.args.network`      | The network name     |

### Semantics

* **One poll per network** — workflows sharing a network share the head poll
  (\~2s interval); every newly observed block number `b` with `b % every == 0`
  fires.
* **Exactly-once** — the claim key is derived from the block number
  (`block:{network}:{number}`), so poll overlap and restarts are duplicates,
  never double fires.
* **Catch-up is capped** — the first poll after boot only anchors the head (no
  historical firing). After an RPC outage, every block in the observed gap is
  considered, capped at the newest **100 blocks** with a warning — a long
  outage on a fast chain does not replay thousands of runs.

For "every block, act on the events in it", prefer an
[event trigger](/workflows/triggers/event) — it decodes and filters for you.
For "poll a value until it crosses a line", prefer a
[read trigger](/workflows/triggers/read) — it is edge-triggered.


## Composite triggers — `all` / `any`

A composite trigger fires a workflow from **several** on-chain events instead of one.

* `trigger.all` — fire **one** run when **every** listed event has matched within a
  sliding correlation window (`within`).
* `trigger.any` — fire when **any** listed event matches (first match).

Each matched event is exposed to the workflow steps as `events.<id>.*` (its decoded
`args`, `tx_hash`, `block_number`, `address`, …).

### `all` — correlate two related events

```yaml
workflows:
  deposit-then-transfer:
    trigger:
      all:
        within: 10m           # sliding correlation window (REQUIRED for `all`)
        events:
          - id: deposit
            event:
              contract: Vault
              name: Deposit
              network: ethereum
          - id: transfer
            event:
              contract: USDC
              name: Transfer
              network: ethereum
              # cross-event correlation: a LATER event's where may reference
              # events.<earlier-id>.args
              where: "${{ event.args.to == events.deposit.args.user }}"
    steps:
      - notify:
          channel: ops
          message: "deposit ${{ events.deposit.args.amount }} then transfer ${{ events.transfer.tx_hash }}"
```

Semantics:

* The **first** listed event opens a correlation; every later event **attaches** to
  the correlation it satisfies. `${{ event.args.* }}` in a `where:` is **this** event;
  `events.<earlier-id>.args` are the already-matched earlier events.
* A later event is consumed by **at most one** correlation — the **oldest** open one
  it satisfies. A single on-chain event never fans out into multiple runs (so one
  settlement transfer can never trigger two payouts). If a cross-event `where:` is not
  fully discriminating (e.g. two deposits by the same user), the oldest window wins and
  the others keep waiting for their own later event.
* When a correlation holds every listed event, the run is claimed **exactly once**
  (a durable dedup key over the matched set — a re-delivered completing event never
  fires a second run).
* Partial matches accumulate in a durable table (`rflow.composite_matches`) and are
  swept once their `within` window passes — an incomplete set never fires.

`within` is **required** for `all` and must be a **positive** duration (a zero window
is rejected). Cross-event `where:` references must point at an **earlier** event in the
list (validation enforces this), and a composite `where:` may reference **only**
`event.*` and `events.<earlier-id>.*` — any other root (`constants`, `secrets`,
`trigger`, `state`, …) is undefined at match time and is rejected by validation.

**Ordering assumption (honest):** only the **first-listed** event opens a correlation,
so `all` assumes the starter is observed **no later** than the events that correlate to
it. Events on different contracts (or networks) are delivered by independent head
callbacks, so a later event emitted in the **same block** as its starter but at a lower
log index can arrive first; with no correlation open yet it is dropped, and that set
never fires. Order the `events:` list so the event most likely to be seen first (or the
one others correlate **back** to) is the starter, or keep the correlated events on the
**same** contract (same-contract logs are delivered in on-chain order). Buffering
out-of-order arrivals is intentionally out of scope — doing it exactly-once would need
a durable consumed-identity tombstone (the arbitrary-CEP join this feature excludes).

A single-event `all` is just an `event:` trigger — `rflow validate` advises you to
model a "react to a follow-up event" flow as an `event:` trigger plus a
[`wait_for:`](/workflows/steps/wait-for) step (the run then correlates with the full
run context).

### `any` — fire on the first of several events

```yaml
    trigger:
      any:
        events:
          - id: paused
            event: { contract: Vault, name: Paused, network: ethereum }
          - id: guardian
            event: { contract: Guardian, name: EmergencyStop, network: ethereum }
    steps:
      - notify: { channel: pager, message: "emergency: ${{ events.paused.tx_hash or events.guardian.tx_hash }}" }
```

`any` fires immediately on the first matching event (deduped by that event's log
identity). `within` is accepted but does not gate `any`.

### Match-time scope + reorgs

Composite events match at chain **head** — the same default an `event:` trigger uses
for an event with no `confirmations:` of its own. Exactly-once completion does **not**
depend on the indexing depth: it rides the durable `rflow.composite_matches`
accumulator, the `composite:{workflow}:{hash}` dedup key, and the sliding `within`
window (a re-delivered completing event re-derives the same key and never fires a
second run). The reorg caveat is the same as a head-firing `event:` trigger: a reorg
can revert a matched event, so a matched-but-not-completed correlation may linger
until its window expires. Keep composite money workflows to values you are comfortable
acting on at head, or gate the payout behind a `send_transaction` `wait_for: confirmed`.

A composite `where:` sees **only** `event.*` (this event) and `events.<earlier-id>.*`
(correlated earlier events) — the same self-contained match-time discipline as
`wait_for`. Addresses are case-normalized, so
`event.args.to == events.deposit.args.user` compares correctly regardless of casing.

### Testing composites

`rflow test <wf> --fixture <file>` rehearses a composite path by supplying the
matched events directly:

```json
{ "events": {
    "deposit":  { "args": { "user": "0xabc", "amount": "1000000" } },
    "transfer": { "args": { "to": "0xabc", "value": "500000" } }
} }
```

**Replay limit (honest):** the fixture asserts the correlated set directly — the
sliding `within` window and the cross-event `where:` matching are **not** re-run in
`rflow test`. Use it to exercise the workflow's steps over a known-correlated set; the
correlation state machine itself is covered by rflow's DB-gated tests.


## Cron trigger

Fire a workflow on a schedule. No chain config needed — a cron → HTTP → notify
project runs with zero networks and zero signers.

```yaml
workflows:
  daily-report:
    trigger:
      cron:
        expression: "0 9 * * *"    # every day at 09:00 UTC
        catch_up: true             # optional — replay ticks missed while down
    steps:
      - id: fetch
        http_call:
          url: https://api.example.com/stats
      - id: report
        notify:
          channel: ops
          message: "daily stats: ${{ steps.fetch.output.body }}"
```

| Field        | Required | Description                                                                                                                                                                                         |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expression` | ✅        | Standard 5-field cron expression (`minute hour day month weekday`)                                                                                                                                  |
| `tz`         | `UTC`    | IANA timezone name, e.g. `Europe/London`. Ticks compute in the named zone (DST-correct); an unknown name is a startup error. `UTC` / `Etc/UTC` mean the plain UTC path. See [Timezones](#timezones) |
| `catch_up`   | `false`  | Replay schedule slots missed while rflow was down — see below                                                                                                                                       |

The trigger payload exposes `trigger.scheduled_for` (the ISO tick) and
`trigger.workflow` to expressions.

### Exactly-once for schedules

Each scheduled firing claims a trigger key derived from its **scheduled time**
(never `now()`), exactly like events claim `chain_id:tx_hash:log_index` — so a
restart around a tick never double-fires.

### catch\_up — missed ticks

By default, a tick that comes due while the process is down is **skipped**: a
restart schedules from the next future occurrence.

With `catch_up: true`, the last fired tick is persisted per workflow
(`rflow.cron_state`) and on boot every slot missed while rflow was down is
claimed — each with its own scheduled-time key, so a repeated boot can never
double-fire the same tick.

:::warning
The catch-up backlog is capped at the newest **100 ticks** — anything older is
dropped with a warning. A week-long outage on a minutely schedule will not
replay ten thousand runs. If a specific missed run must still happen beyond the
cap, fire it manually with `rflow trigger <workflow>`.
:::

### Timezones

By default a cron runs in UTC. Set `tz` to any [IANA timezone
name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) and the
schedule is computed on that zone's **local wall clock**:

```yaml
cron:
  expression: "0 9 * * 1"    # every Monday at 09:00 LOCAL
  tz: "Europe/London"        # 09:00 GMT in winter, 09:00 BST in summer
```

The zone is validated against the IANA database at config-validation time — an
unknown name (`rflow validate` or boot) is a hard error, never silently UTC.

DST is handled honestly:

* **Spring forward** (a skipped hour): a tick that lands in the gap does not
  hang and does not double-fire — it snaps to the first valid instant after the
  gap.
* **Fall back** (a repeated hour): a fixed-time tick fires **once**, not twice.

The dedupe key stays a **UTC instant** regardless of zone, so exactly-once holds
across restarts and daylight transitions exactly as it does for UTC crons.

### Examples

```yaml
cron: { expression: "*/5 * * * *" }                        # every 5 minutes
cron: { expression: "0 * * * *" }                          # hourly, on the hour
cron: { expression: "0 9 * * 1", catch_up: true }          # Mondays 09:00 UTC, replayed if missed
cron: { expression: "0 9 * * 1", tz: "America/New_York" }  # Mondays 09:00 New York time
```

For a fixed cadence (`every: 30s`) rather than a calendar schedule, use the
[interval trigger](/workflows/triggers/interval) — it allows sub-minute
cadences, which cron cannot express.

Combine with [`send_transaction`](/workflows/steps/send-transaction) for DCA and
treasury sweeps, or keep it fully off-chain. To rehearse a cron workflow's steps
without waiting for the schedule, use [`rflow test`](/backtesting#rflow-test--one-run-from-a-fixture).


## Event trigger

Fire a workflow on a decoded onchain event.

```yaml
trigger:
  event:
    contract: USDC              # name in the contracts: registry
    name: Transfer              # event name
    network: ethereum
    where: "${{ trigger.args.value > wei('1000', 6) }}"   # optional filter
    confirmations: 0            # 0 (head, default) | N | finalized
    run_on: confirmed           # unconfirmed | confirmed (default) | both
    start_block: latest         # earliest | latest | <n>
    end_block: live             # live | <n>
    throttle:                   # optional — cap noisy triggers
      threshold: { count: 5, window: 1h }
      cooldown: 10m
```

| Field           | Required    | Description                                                                                      |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `contract`      | ✅           | A [contract registry](/config/contracts) name. Factory-scoped contracts fire for **every child** |
| `name`          | ✅           | The event name from the ABI, e.g. `Transfer`                                                     |
| `network`       | ✅           | A declared [network](/config/networks)                                                           |
| `where`         |             | Filter [expression](/workflows/expressions) — the run only starts when it is true                |
| `confirmations` | `0`         | Depth the event must reach before firing — see below                                             |
| `run_on`        | `confirmed` | Which phase(s) fire: `unconfirmed` \| `confirmed` \| `both` (two-phase) — see below              |
| `start_block`   | `latest`    | Where the cursor starts — see backfill below                                                     |
| `end_block`     | `live`      | `live` tails forever; a number makes a bounded job that exits cleanly                            |
| `throttle`      |             | Durable rate limiting for noisy triggers — see below                                             |

### The trigger context

Inside expressions, the firing event is `trigger.*`:

| Path                                         | Description                                                                                                            |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `trigger.args.<name>`                        | Decoded event arguments (uint256 values stay exact — see [U256 semantics](/workflows/expressions#u256-math-is-strict)) |
| `trigger.tx_hash`, `trigger.log_index`       | Event identity                                                                                                         |
| `trigger.block_number`, `trigger.block_hash` | Position                                                                                                               |
| `trigger.address`                            | The emitting contract (useful with factory-scoped triggers)                                                            |
| `trigger.network`, `trigger.chain_id`        | Where                                                                                                                  |
| `trigger.topics`                             | Raw log topics                                                                                                         |
| `trigger.phase`                              | `unconfirmed` \| `confirmed` — which phase fired this run (see `run_on`)                                               |

### where

One expression, evaluated per event. Combine conditions with `and` / `or` / `not` —
**not** `&&` / `||`:

```yaml
where: "${{ trigger.args.sender in lists.watched_traders and trigger.args.amount0 > wei('1', 18) }}"
```

A `where` that evaluates false skips the event without creating a run. An expression
*error* (typo'd key, bad type) never silently evaluates false — it routes to failure
handling so you see it.

### confirmations

How deep the event must be before the workflow fires: `0` fires at head (the
default — rflow is built to be fast), `N` waits N blocks, `finalized` waits for
chain finality.

Per-chain guidance (what `rflow validate` prints — advice only, never blocking):

| Chain                      | Suggested depth for irreversible actions |
| -------------------------- | ---------------------------------------- |
| ethereum                   | 20                                       |
| base / arbitrum / optimism | 24                                       |
| polygon                    | 200                                      |
| anything else              | 12                                       |

Rule of thumb: **alert at 0, pay at depth.** A head-fired trigger that sends funds
gets a validation warning, because a reorg can orphan the triggering event *after*
your transaction is sent. Full discussion in [Reorgs](/reorgs).

### run\_on — two-phase firing

`confirmations` sets the depth; `run_on` picks which observation(s) of the event
start a run:

* `confirmed` *(default)* — fire once the event reaches the trigger's
  confirmation depth
* `unconfirmed` — fire the moment the event is first seen at head
* `both` — fire **twice** for the same event: once at head, once at depth. Each
  phase claims its own trigger key, so both runs are individually exactly-once.
  Steps distinguish them with `trigger.phase`:

```yaml
trigger:
  event:
    contract: AnyPool
    name: Swap
    network: ethereum
    confirmations: 20
    run_on: both
steps:
  - id: alert            # instant heads-up
    if: "${{ trigger.phase == 'unconfirmed' }}"
    notify: { channel: ops, message: "swap seen at head: ${{ trigger.tx_hash }}" }
  - id: mirror           # money moves only at depth
    if: "${{ trigger.phase == 'confirmed' }}"
    send_transaction: { ... }
```

This is the single-workflow version of the
["alert at head, pay at depth"](/reorgs#alert-at-head-pay-at-depth) pattern.
If the head-fired event is later orphaned by a reorg, the confirmed phase never
comes — pair it with [`on_reorg:`](/reorgs#actionable-reorg-responses--on_reorg)
if you need to compensate for what the unconfirmed phase already did.

:::warning
`run_on: both` with `confirmations: 0` (or absent) collapses into two
effectively head-firing phases — `rflow validate` warns when such a workflow
sends transactions. Give the confirmed phase a real depth. And note that
`run_on: unconfirmed` ignores `confirmations` entirely (it always fires the
moment the event is first seen) — `rflow validate` calls out a depth that
would be silently discarded.
:::

### throttle

Cap how often a noisy trigger may claim runs. After `threshold.count` fired runs
inside `threshold.window`, further matches are **suppressed** (skipped with a log
line, the cursor still advances) until `cooldown` has passed:

```yaml
throttle:
  threshold: { count: 5, window: 1h }
  cooldown: 10m
```

The window counter and the cooldown fence are persisted in Postgres
(`rflow.trigger_throttle`), never in memory — a restart cannot reset a tripped
cooldown. Only events that actually claimed a run count against the window, so
duplicate deliveries never double-count.

Saturation behaviour, stated plainly: if the window has not rolled over when the
cooldown expires, the next fire runs and immediately re-trips the cooldown —
i.e. at most one run per cooldown period until the window resets.

(For limiting a *workflow* rather than a trigger, see
[`rate_limit`](/workflows#rate_limit) — note its window is in-process, unlike
throttle.)

### Backfill and cursors

`start_block` / `end_block` give you history and live tailing in one config:

* `start_block: earliest` — backfill from the contract's first block, then go live
* `start_block: latest` *(default)* — start from now
* `start_block: 19000000` — backfill from a specific block
* `end_block: live` *(default)* — tail forever
* `end_block: 19100000` — bounded job: process the range, exit cleanly

Each `(workflow, network)` pair keeps a **cursor** (last processed block) in
Postgres — visible in `rflow ls` — so restarts resume exactly where they left off and
a crash never skips or re-processes a block range. Combined with the
[exactly-once claim](/reliability), replaying an overlap is harmless: duplicate
events are skipped.

To rehearse a workflow against a historical range without touching live state,
use [`rflow replay`](/backtesting) — it runs an isolated, dry-run-by-default
session over `--from-block`/`--to-block`.

One dev-chain caveat: a trigger with `confirmations: N` live-tailing from the
head of a **fresh local chain** (no history at all, e.g. a just-started anvil)
can panic the embedded indexer's progress tracker (an upstream start == target
edge). Real chains have history; on a fresh anvil give the trigger an explicit
`start_block` (even `1`) so it has a real backfill range.

### Factory-scoped triggers

Point the trigger at a [factory contract](/config/contracts#factory-tracking) and it
fires for every child ever deployed:

```yaml
trigger:
  event:
    contract: AnyPool        # factory: { contract: UniV3Factory, event: PoolCreated }
    name: Swap
    network: ethereum
    where: "${{ trigger.args.sender in lists.watched_traders }}"
```

`trigger.address` tells you which child emitted.

### Reacting to reorgs

If a reorg orphans an event this trigger already fired on, the workflow's
[`on_reorg:`](/reorgs#actionable-reorg-responses--on_reorg) steps run with a
`reorg.*` context — notify, compensate, whatever the situation needs.


## Interval trigger

Fire a workflow on a fixed wall-clock cadence — `every: 30s | 1m | 5m`. No chain
config needed. Unlike [cron](/workflows/triggers/cron), intervals allow
**sub-minute** cadences, so a 30-second keeper needs no cron hacks.

```yaml
workflows:
  price-keeper:
    trigger:
      interval:
        every: 30s          # fire every 30 seconds
        catch_up: false     # optional — skip ticks missed while down (default)
    steps:
      - id: poke
        send_transaction:
          network: ethereum
          relayer: keeper
          to: "0xOracle..."
          function: "poke()"
```

| Field      | Required | Description                                                                                   |
| ---------- | -------- | --------------------------------------------------------------------------------------------- |
| `every`    | ✅        | Fire cadence as a duration (`30s`, `1m`, `5m`, `1h`). Sub-minute is allowed. Must be positive |
| `catch_up` | `false`  | Replay the ticks missed while rflow was down — see [catch-up](#catch-up--missed-ticks)        |

The trigger payload exposes `trigger.scheduled_for` (the ISO instant) and
`trigger.workflow` to expressions.

### Interval vs cron vs read polling

| Use                                                  | Trigger                                               |
| ---------------------------------------------------- | ----------------------------------------------------- |
| A fixed cadence, "every N seconds/minutes"           | **interval** (`every: 30s`)                           |
| A calendar schedule, "09:00 on Mondays", timezones   | [cron](/workflows/triggers/cron) (`expression`, `tz`) |
| Fire only when an on-chain value crosses a threshold | [read](/workflows/triggers/read) (`condition`)        |

### Exactly-once for the cadence

Ticks land on a stable grid anchored at first boot
(`anchor, anchor + every, anchor + 2·every, …`; the first fire is one interval
after boot). Each firing claims a trigger key derived from its **scheduled
instant** — `interval:{workflow}:{ISO}` — never `now()`. A restart landing on
the same instant, or a second scheduler, claims the same key and the duplicate
is skipped. Exactly-once, exactly like events and cron.

The next-due instant is persisted per workflow in `rflow.interval_state`, so the
grid **survives restarts**: the schedule resumes on the same phase instead of
re-anchoring (which would fire immediately on every boot). If you **shorten**
`every` (say `1h` → `30s`) and restart, the stale long cursor is clamped to at
most one new interval out, so the faster cadence takes effect promptly rather
than waiting out the old hour.

### catch-up — missed ticks

Interval catch-up is deliberately **distinct from cron's**. Cron replays a
calendar; an interval replays a fixed-cadence grid off the persisted cursor.

* **`catch_up: false`** (default): ticks that came due while the process was
  down are **skipped**. The cursor jumps forward — staying on the original grid
  phase — to the first instant after now, and the schedule resumes. No missed
  tick is claimed.
* **`catch_up: true`**: on boot every grid instant missed while rflow was down
  is claimed, each under its own scheduled-instant key (so a repeated boot can
  never double-fire).

:::warning
The catch-up backlog is capped at the newest **100 ticks** — anything older is
dropped with a warning. A long outage on a 30-second interval will not replay
thousands of runs.
:::

### Examples

```yaml
interval: { every: 15s }                    # every 15 seconds
interval: { every: 1m }                     # every minute
interval: { every: 5m, catch_up: true }     # every 5 minutes, replayed if missed
```

Combine with [`send_transaction`](/workflows/steps/send-transaction) for keeper
pokes and heartbeats, or keep it fully off-chain. Polling a web feed or API
with interval + `http_call`? The [web trigger](/workflows/triggers/web) does
the fetch, parse, new-item diff and dedupe for you. To rehearse an interval
workflow's steps without waiting for the schedule, use
[`rflow test`](/backtesting#rflow-test--one-run-from-a-fixture) with a
`{ "scheduled_for": "..." }` fixture.


## Query trigger

Poll a read-only SQL **aggregate over the indexed event tables** on an
interval and fire when a condition is met — "page me when 24h volume crosses
X", "act when cumulative deposits pass a threshold" — without an external
cron + API.

```yaml
workflows:
  volume-alarm:
    trigger:
      query:
        sql: >-
          SELECT COALESCE(SUM(value::numeric), 0)
          FROM rflow_indexer_rflow_idx_usdc.transfer
          WHERE block_timestamp > now() - interval '1 hour'
        every: 1m
        condition: "${{ output > wei('10000000', 6) }}"
        mode: threshold          # threshold (default) | changed
    steps:
      - id: alert
        notify:
          channel: ops
          message: "hourly USDC volume crossed 10M: ${{ format_units(trigger.args.output, 6) }}"
```

| Field       | Required    | Description                                                                                                                                                                   |
| ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sql`       | ✅           | ONE read-only statement (`SELECT` / `WITH … SELECT`) — same rules and [table naming](/workflows/steps/query#where-the-data-lives--the-table-naming-rule) as the `query:` step |
| `args`      |             | `$1..$N` values, rendered **once at boot** — only `constants` / `secrets` / `lists` roots (no trigger context exists yet; validated)                                          |
| `every`     | ✅           | Poll interval, e.g. `1m`                                                                                                                                                      |
| `condition` | ✅           | Firing condition over the shaped `output` (alias `result`)                                                                                                                    |
| `mode`      | `threshold` | `threshold` \| `changed` — identical semantics to the [read trigger](/workflows/triggers/read#firing-modes--edge-triggered-never-spam)                                        |

The shaped query output (scalar / object / row array — shaped exactly like
the [`query:` step](/workflows/steps/query#output-shaping)) is what
`condition:` sees; `NUMERIC` values compare as exact numbers, so
U256-scale thresholds are precise.

### Firing modes — edge-triggered, never spam

* **`threshold`** *(default)* — fire on the false→true **crossing** of
  `condition:`. A condition that stays true fires once, not every poll.
* **`changed`** — fire when the shaped output differs from the previous
  poll's while the condition holds (the first observation only records a
  baseline).

The previous poll's state persists per workflow
(`rflow.read_trigger_state`), so a restart mid-"true" does **not** re-fire a
threshold trigger. A transient query failure (database hiccup, table not
created yet) logs, keeps the previous state and retries next poll.

### The trigger context

| Path                        | Description                          |
| --------------------------- | ------------------------------------ |
| `trigger.args.output`       | The shaped query output at fire time |
| `trigger.query.observed_at` | Observation timestamp (ISO)          |

### Exactly-once

Each fire claims `query:{workflow}:{poll instant}` — one run per polling
instant, and the persisted edge state carries the dedupe across restarts.

### Honest notes

* `${{ }}` inside `sql:` is a hard validation error — dynamic values belong
  in `args:` (see the [injection guard](/workflows/steps/query#injection-guard)).
* The statement runs with the default 5s `statement_timeout` inside a
  `READ ONLY` transaction on rflow's own Postgres — keep polled aggregates
  indexed/cheap, or widen `every:`.
* The trigger only sees what the project indexes: event-trigger tables and
  [`contracts.<name>.index_events`](/config/contracts#index_events--index-only-analytics)
  tables (plus the `rflow.*` journal). `rflow tables` lists what is
  queryable.


## Read trigger

Poll a view function on an interval and fire when a condition is met — health
factors, utilization, oracle staleness, anything an `eth_call` can see.

```yaml
workflows:
  high-utilization:
    trigger:
      read:
        contract: LendingPool
        network: ethereum
        function: "getUtilization()"
        every: 1m
        condition: "${{ output > wei('0.95', 18) }}"
        mode: threshold          # threshold (default) | changed
    steps:
      - id: alert
        notify:
          channel: ops
          message: "utilization crossed 95%: ${{ format_units(trigger.args.output, 18) }}"
```

| Field       | Required    | Description                                                         |
| ----------- | ----------- | ------------------------------------------------------------------- |
| `contract`  | ✅           | A [contract registry](/config/contracts) name                       |
| `network`   | ✅           | A declared [network](/config/networks)                              |
| `function`  | ✅           | Solidity signature, e.g. `getUtilization()`                         |
| `args`      |             | Arguments — each may be an [expression](/workflows/expressions)     |
| `every`     | ✅           | Poll interval, e.g. `1m`                                            |
| `condition` |             | Firing condition over the decoded value — omitted, every poll fires |
| `mode`      | `threshold` | `threshold` \| `changed` — see below                                |

The decoded value is available to the `condition:` expression as `output` (alias
`result`), decoded exactly like a [`read:` step](/workflows/steps/read#output).

### Firing modes — edge-triggered, never spam

* **`threshold`** *(default)* — fire when the condition is true **and it was
  false on the previous poll**: a false→true crossing. A condition that stays
  true fires once, not every minute.
* **`changed`** — fire when the decoded value differs from the previous poll's
  (the first observation only records a baseline).

The previous poll's state is persisted per workflow
(`rflow.read_trigger_state`), so a restart mid-"true" does **not** re-fire a
threshold trigger.

### The trigger context

| Path                                            | Description                         |
| ----------------------------------------------- | ----------------------------------- |
| `trigger.args.output` / `trigger.args.value`    | The decoded read value at fire time |
| `trigger.read.function`, `trigger.read.network` | What was polled                     |
| `trigger.read.observed_at`                      | Observation timestamp (ISO)         |

### Exactly-once

Each fire claims `read:{workflow}:{poll instant}` — one run per polling instant,
and the persisted edge state carries the dedupe across restarts.


## Stream trigger (WebSocket)

Start a workflow from messages on an external WebSocket feed — exchange
prices, order books, liquidation feeds, oracle vendor feeds, bridge status,
internal event streams. Each JSON message is filtered by an expression and, if
it matches, becomes an ordinary rflow run.

```yaml
workflows:
  price-spread-alert:
    trigger:
      stream:
        websocket:
          url: ${BINANCE_WS_URL}          # ws:// or wss:// (a ${VAR} placeholder is fine)
          subscribe:
            method: SUBSCRIBE
            params: ["ethusdt@ticker"]
            id: 1
          message_json_path: "$"          # extract the payload object (default $)
          where: "${{ message.s == 'ETHUSDT' and wei(message.c, 8) > wei('3500', 8) }}"
          idempotency_key: "${{ message.E }}"
    steps:
      - notify:
          channel: ops
          message: "ETH at ${{ trigger.args.c }}"
```

:::warning
This is **durable automation, not HFT.** A matched message flows through
rflow's normal claim + throttle + rate-limit path into a journaled run with
recovery and history — it is **not** a low-latency trading engine, and a
third-party stream that does not carry a stable message id is **not**
exactly-once. Non-goals: sub-millisecond trading, mempool strategies, exchange
account management.
:::

### The `message` root

Every frame is parsed as JSON (v1 is JSON-only) and narrowed by
`message_json_path` (default `$`, the whole frame; supports `$.a.b` and
`$.a[0]`). The result is the **`message`** root — the only root the `where`
and `idempotency_key` expressions can see.

* a frame that is **not JSON**, or where the path **selects nothing**, is
  dropped with a warning (never a crash)
* `where` **false** fires nothing; omit `where` to fire on every message
* `wei(message.c, 8)` parses a decimal price string to an exact integer for a
  precise numeric comparison (minijinja has no float coercion)

The run payload is `{ args: <message>, stream: { url_host, received_at } }`, so
steps address the message as `trigger.args.*`.

### Exactly-once under reconnect

| `idempotency_key`                 | dedupe key                                                                                                                           | reconnect behaviour                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| **set** (e.g. `${{ message.E }}`) | `stream:{workflow}:{sha256(key)}` via the [webhook-idempotency](/workflows/triggers/webhook#idempotency--dedupe-caller-retries) gate | a replayed message inside `idempotency_ttl` (default 7d; 1m–365d) creates **no new run** |
| **absent**                        | `stream:{workflow}:{uuid}` per message                                                                                               | a reconnect that re-delivers messages **can duplicate** — documented at-least-once       |

Set `idempotency_key` to a **stable id** the feed provides (an event time, a
sequence number, a trade id). A feed without one cannot be exactly-once — drop
the key and accept at-least-once, or dedupe downstream.

The key must be a **pure function of `message`**. A non-deterministic expression
(e.g. one calling `now()`) would render a different key for every delivery, so
the hash never collides and dedupe silently does nothing — `rflow validate` and
boot **reject** it rather than let you ship a broken exactly-once.

### Resilience

| field               | default         | behaviour                                                                                                                                                                                                                                |
| ------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| connect             | 15s timeout     | a failed/slow connect retries with backoff                                                                                                                                                                                               |
| `reconnect`         | enabled, 1s→60s | exponential backoff on any drop (reset after a healthy session); `enabled: false` exits on the first drop                                                                                                                                |
| `heartbeat`         | off             | send a WebSocket ping every interval **and** treat it as a liveness probe — if no frame or pong arrives for a few intervals the connection is silently dead (half-open) and is reconnected, instead of the read loop parking on a corpse |
| `max_message_bytes` | 1 MiB           | an oversize frame is dropped with a warning (a hard 32 MiB frame closes the connection)                                                                                                                                                  |
| `throttle`          | off             | same window/cooldown as [`trigger.event.throttle`](/workflows/triggers/event) — caps a chatty feed                                                                                                                                       |

The read loop never blocks on the journal: matched messages go onto a bounded
queue drained by a claim worker, so a slow database **sheds load** (a warning)
rather than stalling reads (which would starve pongs and drop the socket). The
stream task is owned by the running stack and shut down cleanly — no leaked
task or socket on shutdown or a `--watch` reload. The closing handshake is
itself bounded, so a backpressured or half-open peer cannot wedge teardown.

### Redaction

The URL may embed a token (in its query or userinfo). Only the **host** is ever
journaled or logged (`stream.url_host`) — the full URL, and any token in it,
never lands in a payload or a log line.

### Rehearse offline

`rflow test <workflow> --fixture <file>` builds the trigger payload from a
fixture that is the extracted `message` object (bare, or wrapped as
`{ "message": {...} }`), so you can exercise the `where` filter and the steps
without touching the internet.

See the [price alert stream](/use-cases/price-alert-stream) use case for a
full template. For pull-style web sources (RSS/Atom feeds, JSON endpoints,
HTML pages) there is no socket to hold open — poll them with the
[web trigger](/workflows/triggers/web) instead.


## Web trigger (HTTP poll)

Start a workflow from a web data source — protocol announcements, governance
forum posts, security advisories, oracle incident pages, exchange listings,
risk feeds, status pages, internal APIs. rflow polls an HTTP(S) URL on an
interval, parses the body into **items** (RSS/Atom entries, JSON array
elements, or the text of HTML nodes), and fires one run per **new** item —
or one run per **content change** with `changed: true`.

```yaml
workflows:
  security-advisory-watch:
    trigger:
      web:
        url: https://example.com/security/feed.xml
        every: 5m
        mode: rss
        where: "${{ 'critical' in (item.title | lower) }}"
        idempotency_key: "${{ item.link }}"
    steps:
      - notify:
          channel: pager
          message: "Security advisory: ${{ item.title }} ${{ item.link }}"
```

HTML change detection:

```yaml
trigger:
  web:
    url: https://example.com/status
    every: 1m
    mode: html_text
    selector: ".incident"
    changed: true
```

:::warning
**Web signals yes — browser automation no.** rflow fetches and parses; it
never logs in, clicks buttons, solves captchas, or drives a browser, and it
is not a search-engine crawler or a scraping platform. That boundary is
deliberate. If a source needs a real browser, call an external tool from a
[`command:` step](/workflows/steps/command) and let rflow journal the result.
:::

### Fields

| Field             | Required             | Description                                                                                                                                                                   |
| ----------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`             | yes                  | `http://` or `https://` endpoint. `${VAR}` placeholders resolve at boot. A token in the query string is never journaled or logged — payloads carry scheme+host+path only.     |
| `every`           | yes                  | Poll interval, e.g. `5m`. **Floor 30s** (validated) — see [etiquette](#etiquette-be-a-polite-citizen).                                                                        |
| `mode`            | yes                  | `rss` \| `atom` \| `json` \| `html_text` — how the body parses into items (below).                                                                                            |
| `selector`        | `html_text` only     | CSS selector; each matching node's (whitespace-normalized) text is one item. Required for `html_text`, rejected for other modes.                                              |
| `path`            | `json` only          | JSON path selecting the item array (default `$`, the whole body). Supports `$`, `$.a.b`, `$.a[0]`. A non-array selection is ONE item.                                         |
| `where`           | no                   | Item filter over the `item` root, e.g. `${{ 'critical' in (item.title \| lower) }}`. Only matching items fire; with `changed: true` only matching items are fingerprinted.    |
| `changed`         | no (default `false`) | `true` = change detection: fingerprint the whole (filtered) item list and fire ONE run when it differs from the previous poll.                                                |
| `idempotency_key` | no                   | Dedupe identity over `item`, e.g. `${{ item.link }}`. Default: the item's content fingerprint. Must be a pure function of the item — `now()` etc. are rejected.               |
| `timeout`         | no (default `30s`)   | Per-fetch timeout.                                                                                                                                                            |
| `max_body_bytes`  | no (default 2 MiB)   | Streaming body cap (hard ceiling 32 MiB). An oversize body **fails the poll loudly** — never a silent truncation.                                                             |
| `headers`         | no                   | Extra request headers, e.g. `Authorization: "Bearer ${{ secrets.token }}"`. Values render once at boot (constants/secrets/lists roots) and are **never journaled or logged**. |

### Modes → items

| `mode`         | one item is                                                                         | item shape                                                          |
| -------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `rss` / `atom` | one feed entry                                                                      | `{ id, title, link, published, summary }` (missing fields are `""`) |
| `json`         | one element of the array at `path` (or the whole selection when it is not an array) | the JSON value as-is                                                |
| `html_text`    | the text content of one node matching `selector` (empty-text nodes are skipped)     | `{ text }`                                                          |

A mislabeled feed is a loud error (`mode: rss` against an Atom document tells
you to use `mode: atom`), as are an unparseable body, a JSON `path` that
selects nothing, and a non-2xx status — every failure is logged with the
workflow and the redacted URL, and retried on the next tick. **No silent
skips.**

### The `item` root

Steps in a web-triggered workflow see the fired item under **`item.*`** (as
the spec examples read) and, like every trigger, under `trigger.args.*`; the
poll metadata rides under `trigger.web.*` (`url` (redacted), `mode`,
`fingerprint`, `observed_at`). A `foreach:` step's own `item` shadows the
trigger's inside that step — the full item stays addressable as
`trigger.args.*`.

`where` and `idempotency_key` evaluate over the **`item` root only** — any
other root is a validation error.

### New-item detection and dedupe

Every (filtered) item is fingerprinted — SHA-256 over a canonical
serialization — and persisted in `rflow.web_trigger_fingerprints`. Each poll
diffs against the store and claims one run per NEW fingerprint through the
same idempotency gate webhooks and streams use, under
`web:{workflow}:{sha256(key)}`:

* **default key = the fingerprint** — an *edited* item (title or summary
  touch-up) counts as new and fires again
* **`idempotency_key: "${{ item.link }}"`** keys on a stable id instead, so
  edits never re-fire — this is what "duplicate web items do not create
  duplicate runs when keyed" means
* the **first successful poll on a fresh store records a baseline and fires
  nothing** — booting on an established feed does not fire its whole history
* the store is capped per workflow (oldest-seen items age out only after they
  leave the feed), so an unbounded feed cannot grow it forever.

### `changed: true` — content change detection

Instead of per-item diffing, the whole (filtered) item list is fingerprinted
as one content blob; when it differs from the previous poll, ONE run fires
with `{ count, items }` as the item, plus `trigger.web.previous_fingerprint`.
The first observation is a baseline; a revert (A→B→A) fires again, like
`trigger.read`'s `changed` mode. Combine with `where` so an irrelevant part
of the page never fires: only matching items are fingerprinted.

### Etiquette — be a polite citizen

A web poller is a guest on someone else's server:

* every fetch sends an **`rflow/<version>` User-Agent**, so source operators
  can identify (and contact, and rate-limit) the traffic
* **respect robots.txt and the source's published rate limits.** rflow does
  not fetch robots.txt for you — you choose the URL and cadence; choose ones
  the operator allows
* the `every` floor is **30s**, and the right value is usually much larger —
  poll no faster than the content actually changes (a security feed updates
  hourly, not secondly); prefer feeds/APIs over HTML pages when offered
* defaults are conservative: 30s timeout, 2 MiB body cap, at most 5
  redirects
* rflow never hammers on failure — a failed poll waits for the next tick,
  exactly like a successful one.

### Redaction

Feed and API URLs often carry keys in their query string. Payloads and logs
only ever carry **scheme+host+path**; request headers (where credentials
belong) are never journaled or logged, and header values are redacted in
config-version snapshots.

### Rehearse offline

`rflow test <workflow> --fixture <file>` builds the trigger payload from a
fixture that is one parsed item (bare, or wrapped as `{ "item": {...} }`), so
you can exercise the steps without touching the source.

See the [security advisory watch](/use-cases/security-advisory-watch) use
case for a full template, and the [stream trigger](/workflows/triggers/stream)
for push-style (WebSocket) external signals.


## Webhook trigger

Fire a workflow on an inbound HTTP POST. The route lives below rflow's single
port (`config.port`) — no extra listener, no extra exposure.

```yaml
secrets:
  HOOK_KEY: ${BACKEND_HMAC_KEY}

workflows:
  deposit-hook:
    trigger:
      webhook:
        path: /hooks/deposit
        auth: hmac
        secret: "${{ secrets.HOOK_KEY }}"
    steps:
      - id: ack
        notify:
          channel: ops
          message: "deposit webhook: ${{ trigger.args.user }} / ${{ trigger.args.amount }}"
```

```bash
curl -X POST localhost:3940/hooks/deposit \
  -H "content-type: application/json" \
  -H "x-rflow-signature: $(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$KEY" -r | cut -d' ' -f1)" \
  -d "$BODY"
```

| Field             | Required          | Description                                                                                                                                                              |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`            | ✅                 | Route below rflow's port, e.g. `/hooks/deposit`. Must start with `/` and be unique across workflows (validated)                                                          |
| `auth`            | `none`            | `hmac` \| `none` — see below                                                                                                                                             |
| `secret`          | with `auth: hmac` | The shared secret — usually `${{ secrets.<name> }}` so it stays log-redacted                                                                                             |
| `idempotency_key` | —                 | Dedupe identity for caller retries — an expression over the **request** (`headers`, `body`, `path`, `query`, `method`); [see below](#idempotency--dedupe-caller-retries) |
| `idempotency_ttl` | `7d`              | How long a key claims its run — min `1m`, max `365d`. A **re-use window**, not a retention guarantee                                                                     |
| `on_duplicate`    | `return_existing` | Duplicate response: `return_existing` \| `accepted` \| `conflict` — [see the table](#responses)                                                                          |

### The trigger context

The JSON request body becomes `trigger.args.*`; the envelope is under
`trigger.webhook.*`:

| Path                          | Description                                          |
| ----------------------------- | ---------------------------------------------------- |
| `trigger.args.<key>`          | The parsed JSON body (empty map for body-less POSTs) |
| `trigger.webhook.path`        | The route that received it                           |
| `trigger.webhook.received_at` | Receipt timestamp (ISO)                              |

### Authentication

`auth: hmac` verifies the `x-rflow-signature` header as the lowercase hex
HMAC-SHA256 of the **raw body bytes** under `secret` — exactly the signature an
[`http_call`](/workflows/steps/http-call#hmac-signing) step *sends*, so two
rflow instances can call each other with zero glue. A bad or missing signature
is rejected before anything is claimed.

`auth: none` (the default) relies on network-level protection. rflow's port is
designed as a localhost / private-network operator tool — see the
[observability warning](/observability) before exposing it anywhere.

### Delivery semantics — at-least-once, honestly

Without `idempotency_key`, every accepted POST claims a fresh trigger key
(`webhook:{path}:{uuid}`), so a caller that retries after a network blip
**creates a second run**. This is deliberate: webhooks have no *inherent*
dedupe identity (unlike a chain log or a cron tick), and inventing one from
the body would silently drop distinct calls. Callers own their retry dedupe;
the HTTP response body carries the `run_id` for correlation.

Paused workflows answer **429** instead of claiming — the caller's retry loop
naturally redelivers once the workflow is resumed. One exception when
`idempotency_key` is configured: a delivery whose key already holds a **live
claim** still answers per `on_duplicate` while paused (a read-only lookup —
no run is created). Without that, a pause longer than the key's remaining TTL
would keep the caller retrying past the duplicate answer, and the first retry
after unpause would re-open the expired key and run the workflow a *second*
time.

### Idempotency — dedupe caller retries

Declare the request's **business identity** and rflow dedupes retries for you:

```yaml
trigger:
  webhook:
    path: /hooks/deposit
    auth: hmac
    secret: "${{ secrets.HOOK_KEY }}"
    idempotency_key: "${{ headers['x-idempotency-key'] }}"
    idempotency_ttl: 7d              # default; min 1m, max 365d
    on_duplicate: return_existing    # default; accepted | conflict
```

The key is an expression over the **request** — five roots are in scope
(and only these five; `rflow validate` rejects anything else):

| Root      | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| `headers` | Header map, names lowercased — `${{ headers['x-idempotency-key'] }}` |
| `body`    | The parsed JSON body — `${{ body.event_id }}`                        |
| `query`   | Decoded query-string pairs — `${{ query.id }}`                       |
| `method`  | The HTTP method (`POST`)                                             |
| `path`    | The route that received the delivery                                 |

Semantics:

* the evaluated key (hashed) becomes the claim identity
  `webhook:{workflow}:{sha256(key)}` — a duplicate POST with the same key
  within `idempotency_ttl` creates **no** new run and answers per
  `on_duplicate` (see the table below)
* a key that fails to evaluate (e.g. the header is missing) or evaluates to
  an **empty string** is a `400` and nothing runs — fix the request, don't
  retry it as-is
* the TTL is a **re-use window**, not a retention guarantee: after expiry
  the same key may claim a *new* run (pick a TTL longer than your callers'
  longest retry horizon)
* a **paused** workflow still answers duplicates: a key with a live claim
  answers per `on_duplicate` (read-only, no run created); only keys with no
  live claim get the paused `429` — so pausing never stretches a caller's
  retry loop past the duplicate answer
* the raw key + expiry are stored in `rflow.webhook_idempotency` (queryable
  by operators); expired rows are pruned on boot and opportunistically
* **redaction**: headers are visible to the key expression only — they are
  never journaled in the run's trigger payload or logged (logs carry the key
  hash). The evaluated **key itself** is stored in **plaintext** in
  `rflow.webhook_idempotency.raw_key` for the length of the TTL, so do *not*
  derive keys from secret-bearing headers (`authorization`, signatures) —
  use a caller-supplied `x-idempotency-key` or a business identity from the
  body instead

Without `idempotency_key` nothing changes — today's uuid-per-delivery
behaviour is untouched.

`rflow validate` prints **advice** (never blocking) when a webhook-triggered
workflow sends transactions without an `idempotency_key`; `rflow doctor`
carries the same nuance next to its webhook auth check.

### Responses

First delivery (unchanged):

| Status | Meaning                                                                                                                                  |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `202`  | Run claimed — body carries the `run_id`                                                                                                  |
| `200`  | Accepted but no run claimed (`run_id: null`)                                                                                             |
| `400`  | `idempotency_key` failed to evaluate or was empty — body carries `error`                                                                 |
| `401`  | HMAC verification failed                                                                                                                 |
| `429`  | The workflow is paused — with `idempotency_key`, only when the key holds no live claim (live duplicates still answer per `on_duplicate`) |
| `404`  | No workflow declares this path                                                                                                           |

Duplicate delivery (same `idempotency_key` within the TTL), per `on_duplicate`:

| Mode                        | Status | Body                                                                    |
| --------------------------- | ------ | ----------------------------------------------------------------------- |
| `return_existing` (default) | `200`  | `{"status":"duplicate","run_id":"<original>","run_status":"<current>"}` |
| `accepted`                  | `202`  | `{"status":"duplicate"}` — no ids leaked                                |
| `conflict`                  | `409`  | `{"status":"duplicate","run_id":"<original>"}`                          |


## `choose` — readable branching

`choose` runs the **first** branch whose `if:` is true (or the trailing `else`), and
**nothing else**. It replaces long chains of negative `if:` conditions with one
readable block.

```yaml
steps:
  - id: risk
    command: { run: "node ./score.js" }
  - id: route
    choose:
      - if: "${{ steps.risk.output.level == 'high' }}"
        steps:
          - notify: { channel: pager, message: "high risk ${{ trigger.tx_hash }}" }
      - if: "${{ steps.risk.output.level == 'medium' }}"
        steps:
          - send_transaction:
              network: ethereum
              relayer: ops
              contract: Vault
              function: "flag(bytes32)"
              args: ["${{ steps.risk.output.id }}"]
              approval: { via: [cli] }
      - else:
          steps:
            - notify: { channel: ops, message: "low risk" }
```

### Rules

* Branches evaluate **in order**; the first true `if:` wins. Only one branch runs.
* At most one `else`, and it must be **last** (validation enforces both).
* Nested branch steps are **ordinary journaled steps** — they retry, resume and stay
  exactly-once exactly like top-level steps. A `send_transaction` inside a branch keeps
  its `external_id` discipline (no double-send).
* Nested steps are journaled under the stable id `<chooseId>/<branchIdx>/<stepId>`
  (visible in `rflow runs show`); they reference siblings and outer steps by their
  declared id (`steps.<id>`).

### Crash-safety

The **branch decision is journaled** before any nested step runs, so a crash mid-branch
resumes into the **same** branch — even if a mutable `state.*` / `lists.*` value the
`if:` read has since changed. Already-settled nested steps are never re-run on resume.

### Limits

To keep the branch a plain journaled sequence (no goto, no fan-out), a `choose` branch
may **not** contain `wait_for`, `foreach`, or a nested `choose` (validation rejects
them). Every other step kind is allowed.


## command

Run a project-owned command that **decides, transforms, enriches, scores, or
prepares** data. rflow renders an `input:` object, pipes it to the command as
JSON on stdin, and stores what the command prints on stdout as
`steps.<id>.output` for later steps to consume.

```yaml
- id: decide
  command:
    run: "node ./scripts/decide.js"
    timeout: 10s
    output: json
    input:
      trigger: "${{ trigger }}"
      balance: "${{ steps.balance.output }}"
    env:
      PRICE_API_KEY: "${{ secrets.PRICE_API_KEY }}"

- id: execute
  if: "${{ steps.decide.output.should_send == true }}"
  send_transaction:
    args: ["${{ steps.decide.output.amount }}"]
    recheck: "${{ now() < steps.decide.output.valid_until }}"
```

### The boundary: decide vs execute

`command` is an **action-preparation step, not an execution authority.**

> The command may decide, transform, and prepare data. rflow still owns
> **signing, transaction submission, simulation, approvals, gas caps,
> idempotency, rechecks, history, and durable state.**

The command has **no signing access and no rflow send API**. If a transaction
should happen, the command returns structured parameters and a normal
[`send_transaction`](/workflows/steps/send-transaction) step performs it — so
simulation, gas caps, relayer policy, idempotency, approvals, and rechecks all
still apply. This keeps the run history able to show *exactly* why money moved.

The [command-trade-prep example](https://github.com/joshstevens19/rflow/tree/master/examples/command-trade-prep)
runs this end to end; the [command-decision example](https://github.com/joshstevens19/rflow/tree/master/examples/command-decision)
shows the monitoring-only shape (no signer at all).

### Invocation: `run` vs `program` + `args`

Set **exactly one** of `run` or `program` (both, or neither, is a validation
error).

```yaml
command:
  run: "node ./scripts/decide.js --mode quote"   # convenient, portable
```

```yaml
command:
  program: node                                  # explicit, unambiguous
  args: ["./scripts/decide.js", "--mode", "quote"]
```

* **`run`** is split into a program plus inline arguments by shell-style **word
  splitting** and then spawned **directly — no shell is ever invoked.** That
  means `|`, `&&`, `>`, `$(...)`, backticks, globbing and `$VAR` interpolation
  are **not** interpreted; they become literal arguments. `run` is for
  convenience and portability from other tools, not for shell pipelines. If you
  need a pipeline, put it in a script and call the script.
* **`program` + `args`** spawns the program with the exact args — the safer form
  that avoids any word-splitting ambiguity. Prefer it for anything non-trivial.
* **`args`** may accompany **either** form; its entries are rendered as
  [expressions](/workflows/expressions) and appended after any inline args.

### The stdin / stdout contract

**stdin** — the rendered `input:` object, serialized as a JSON object (the empty
object `{}` when `input:` is omitted). Read it all, then parse:

```js
#!/usr/bin/env node
const chunks = [];
for await (const chunk of process.stdin) chunks.push(chunk);
const input = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
// ...decide...
process.stdout.write(JSON.stringify({ should_send: true, amount: "100000000" }));
```

**stdout** — controlled by `output:`:

| `output:`          | Behaviour                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `json` *(default)* | stdout (trimmed) is parsed as JSON into `steps.<id>.output`. Unparseable stdout fails the step `command_output_invalid` |
| `text`             | stdout is stored verbatim as a string                                                                                   |

**stderr** is advisory only — it never becomes the step's output. On a non-zero
exit an excerpt is surfaced in the failure message (redacted, see below).

Keep output **small and structured** — it lives in the journal, CLI, and API. If
a command produces bulk data, store it externally and return a pointer
(`{ "report_url": "s3://…", "summary": "42 checked, 3 alerts" }`).

### Context injection via `input`

rflow does **not** dump the whole runtime context into the command — that would
widen secret exposure and make inputs unstable. You pass exactly what the
command needs. Every value is a normal expression, so any root works:
`trigger`, `steps`, `state`, `lists`, `constants`, `secrets`, `relayers`
(addresses only — never signing handles), `contracts`, `matrix`, `run`, and
`reorg` (inside [`on_reorg`](/reorgs)).

```yaml
input:
  trigger: "${{ trigger }}"
  balance: "${{ steps.balance.output }}"
  relayer_address: "${{ relayers.main.address }}"
```

Passing whole roots wholesale — especially `input: { secrets: "${{ secrets }}" }`
— triggers a `validate` warning. Reference individual secrets instead.

### Environment

The child does **not** inherit rflow's process environment. Its env is a
**minimal safe base** (`PATH`, `HOME`) plus the rendered `env:` map — nothing
else leaks in. Pass secrets a script needs through `env:` (redacted in logs),
never through stdout:

```yaml
env:
  QUOTE_API_KEY: "${{ secrets.QUOTE_API_KEY }}"
```

### Fields

| Field              | Default           | Description                                                                                                                                                                                                   |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run`              |                   | Executable + inline args, word-split, spawned with no shell. Exclusive with `program`                                                                                                                         |
| `program`          |                   | Executable name/path. Exclusive with `run`                                                                                                                                                                    |
| `args`             |                   | Argument list (expressions); appended after any inline `run` args                                                                                                                                             |
| `cwd`              | project root      | Working directory (rendered; resolved relative to the project root when not absolute)                                                                                                                         |
| `input`            | `{}`              | Object rendered to a JSON object on stdin                                                                                                                                                                     |
| `env`              |                   | Explicit env values (rendered), layered over the minimal base                                                                                                                                                 |
| `timeout`          | `30s`             | Wall-clock limit; may be templated (rendered, then range-checked 1..=600s at run time). Hard max **600s** (a larger static value is a validation error). On timeout the process is killed → `command_timeout` |
| `output`           | `json`            | `json` \| `text`                                                                                                                                                                                              |
| `dry_run`          | `execute`         | `execute` \| `skip` — what replay/test/dry-run does, see below                                                                                                                                                |
| `max_stdout_bytes` | `1048576` (1 MiB) | Exceeding it fails `command_output_too_large`                                                                                                                                                                 |
| `max_stderr_bytes` | `65536` (64 KiB)  | stderr excess is truncated (advisory only)                                                                                                                                                                    |

### Failure taxonomy

Each mode maps to a stable [failure kind](/workflows#retries-and-the-failure-taxonomy) you can
match in `retry.retry_if`:

| Kind                       | Cause                                                | Retryable by default |
| -------------------------- | ---------------------------------------------------- | -------------------- |
| `command_failed`           | non-zero exit                                        | ❌                    |
| `command_timeout`          | killed on timeout                                    | ✅                    |
| `command_output_invalid`   | stdout not parseable for `output: json`              | ❌                    |
| `command_output_too_large` | stdout over `max_stdout_bytes`                       | ❌                    |
| `command_spawn_failed`     | executable missing / not executable / not resolvable | ✅                    |

Override any default with [`retry`](/workflows#retries-and-the-failure-taxonomy).

### Dry-run, test & replay

By **default a command executes for real** even in dry-run (`dry_run: execute`) —
because it may be needed to produce the would-be transaction parameters a later
step rehearses. rflow skips *its own* side effects in dry-run
([`send_transaction`](/workflows/steps/send-transaction) stops before the
relayer, `http_call`/`notify` never fire), but **it cannot know what arbitrary
local code does** — a script that writes files or calls external APIs still
does so.

If a command has side effects you don't want during a rehearsal, set
`dry_run: skip`. It short-circuits **without spawning the process**, settling:

```json
{ "skipped": true, "reason": "command dry_run: skip" }
```

See [Backtesting](/backtesting) for the full replay/test model.

### Redaction & security

* Every outcome passes rflow's shared redaction choke point, so a `secrets.*`
  value echoed into a failure message or stderr excerpt is replaced with a
  `[redacted:NAME]` marker before it reaches the journal, logs, or
  `rflow runs show`. (Successful output is **not** auto-redacted — see below.)
* **Marking specific output fields as secret is not in v1.** Keep secrets **out
  of stdout**; if you must persist one, write it via a later
  [`state_set`](/workflows/steps/state-and-lists), not by returning it.
* Commands run with **your local machine's permissions**. Treat scripts as
  trusted code you own. A command outside the project root (absolute path or
  `..`) raises a `validate` warning.
* **No implicit signing.** The command cannot sign or send; only a later
  `send_transaction` moves money, with all of rflow's guarantees. A command that
  brings its own key/RPC and sends directly **bypasses every guarantee** — this
  is the explicit anti-pattern the linter warns about.

### Sharing output across steps and workflows

Within a workflow, later steps read `steps.<id>.output` directly — through `if:`
gates, [`send_transaction`](/workflows/steps/send-transaction) args,
[`state_set`](/workflows/steps/state-and-lists), `notify`, and `http_call`.

**Across** workflows, do not make another run implicitly depend on this run's
in-memory output. Hand it off **explicitly**:

* **Durable state** — `state_set` the decision; another workflow reads
  `state['…']` in a `where:` or step.
* **List mutation** — `list_add` a wallet the command classified; another
  workflow's trigger matches on `lists.<name>`.
* **Webhook** — `http_call` a second workflow's [webhook
  trigger](/workflows/triggers/webhook) with an idempotency key.

See [state & lists](/workflows/steps/state-and-lists) for the mechanics.

### Validation & preflight

`rflow validate` performs **static checks only** — it never executes your
command. It checks the field shape (`run` xor `program`), timeout/output/dry-run
validity, the 600s timeout ceiling, and that expressions in `run`, `program`,
`args`, `cwd`, `env`, and `input` parse and reference only earlier steps. It
**warns** on: shell-like `run` strings, paths outside the project, `${{ secrets }}`
passed wholesale, a missing (defaulted) timeout, an above-default stdout cap, and
a command placed before a `send_transaction` that has no `recheck:`.

To debug a command against real input **without firing the whole workflow**, use
`rflow command test`:

```bash
rflow command test <workflow> <step-id> --input ./fixtures/context.json
```

It renders the step exactly as a run would — the `--input` fixture supplies the
dynamic context roots (`trigger`, `steps`, `state`, …) the command's
`input:`/`env:`/`args:` reference, while the static roots
(`constants`/`secrets`/`contracts`/`lists`) come from `rflow.yaml` — then runs
the command **for real** and prints the rendered invocation, the (secret-redacted)
stdin, the duration, and the parsed output. Nothing is signed, sent, journaled,
or persisted, and it needs no database; the process exits non-zero when the
command fails, so a fixture doubles as a CI check. Add `--json` for a machine
transcript.

```
command test - 'supply-watch' / 'decide'
 field    | value
 program  | node ./scripts/decide.js
 cwd      | /path/to/examples/command-decision
 duration | 24ms

stdin (rendered input, secrets redacted):
  { "decimals": 18, "run": "command-test", "supply": "1000000000000000000000000" }

output (-> steps.decide.output):
  { "severity": "warning", "reason": "…", "supply": "1000000" }
```

`rflow validate --preflight` adds **command-aware live checks** alongside its
RPC/channel/database pings: for every command step it confirms the executable
resolves (on `PATH`, or as a project-relative path with the executable bit),
that a statically-detectable local script argument (`./scripts/decide.js`)
exists, and — for a known interpreter — reports its version:

```
 command supply-watch/decide | node | ok | resolves on PATH (/usr/local/bin/node); v25.9.0
```

Anything behind a `${{ }}` expression is rendered at run time, so preflight
reports it as skipped rather than guessing.

:::info
An opt-in command **smoke test** (running the command with
`RFLOW_COMMAND_PREFLIGHT=1` during preflight) is still on the roadmap. For a full
end-to-end rehearsal today, `rflow command test` runs the command with real
input, and [`rflow test`](/backtesting#rflow-test--one-run-from-a-fixture) runs
the whole workflow once in dry-run.
:::

### Allowed contexts

`command` is a read-only preparation step, so it is allowed **everywhere** a
normal step is — including inside [`foreach`](/workflows#foreach--fan-a-step-out) fan-outs and
inside [`on_reorg`](/reorgs) handlers (it is not a send, so it is not on
`on_reorg`'s rejected-action list).


## delay

Pause the run for a duration — **durably**.

```yaml
steps:
  - id: submit
    send_transaction: { ... }
  - delay: 30s
  - id: verify
    read: { ... }
```

The action is just the duration string: `30s`, `5m`, `2h`, `1d`.

### Durable means durable

`delay` is not a sleep. The wake-at timestamp is persisted to the journal
(`waiting_delay` state) *before* the wait starts, so:

* a restart or crash mid-delay resumes the countdown against the persisted wake
  time — it neither resets nor skips
* a delay that elapsed while the process was down fires immediately on recovery
* long delays (hours, days) are safe and cost nothing while parked

### When to use it

* settling time between a send and a verification read
* pacing between actions to a rate-limited API
* fixed "wait then check" patterns — when you are waiting for a *specific
  onchain event* rather than a duration, use the
  [`wait_for:` step](/workflows/steps/wait-for) instead (it races events
  against a timeout)


## http\_call

Outbound HTTP with templated url/body and optional HMAC signing.

```yaml
- id: notify-backend
  http_call:
    url: ${BACKEND_URL}/hooks/trade
    method: POST
    headers:
      x-api-key: "${{ secrets.API_KEY }}"
    hmac: "${{ secrets.HOOK_KEY }}"
    body:
      trader: "${{ trigger.args.sender }}"
      amount: "${{ trigger.args.amount0 }}"
      src: "${{ trigger.tx_hash }}"
```

### Fields

| Field     | Required | Description                                                                               |
| --------- | -------- | ----------------------------------------------------------------------------------------- |
| `url`     | ✅        | Templated request url                                                                     |
| `method`  |          | Defaults to `POST` when a `body` is set, `GET` otherwise                                  |
| `headers` |          | Map of headers — values are templates                                                     |
| `body`    |          | A YAML mapping rendered recursively — every string leaf is a template — then sent as JSON |
| `hmac`    |          | Secret used to sign the request — see below                                               |

### HMAC signing

When `hmac:` is set, rflow computes HMAC-SHA256 over the **raw request body bytes**
(the empty byte string for body-less requests) and sends the lowercase hex digest as
the `x-rflow-signature` header. Your backend verifies with the shared secret —
typically one from [`secrets:`](/config/constants-secrets-lists#secrets) so it never
appears in logs.

```python
# receiver side (python)
expected = hmac.new(key, request_body_bytes, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["x-rflow-signature"])
```

### Output and failure mapping

A 2xx response succeeds with output:

```json
{ "status": 200, "body": { ... } }
```

`body` is parsed as JSON when possible, kept as a string otherwise — so
`${{ steps.notify-backend.output.body.some_field }}` works against JSON APIs.

Non-2xx responses map into the failure taxonomy: 5xx and 429 are retryable
(`rate_limited` / retryable kinds) under a `retry:` block; 4xx are terminal. Timeouts
are `rpc_timeout`-class and retryable.

```yaml
  retry:
    max_attempts: 3
    backoff: 10s
```


## notify

Send a templated message to a configured [notification channel](/config/notifications).

```yaml
- id: report
  notify:
    channel: ops
    message: "mirrored ${{ format_units(trigger.args.value, 6) }} USDC — ${{ steps.mirror.tx.hash }}"
```

### Fields

| Field     | Required | Description                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| `channel` | ✅        | A channel declared under `notifications.channels`              |
| `message` | ✅        | Full template — any [expression](/workflows/expressions) works |

### Behavior

* The message renders against the full run context — trigger, prior steps,
  constants, relayer addresses.
* Values from [`secrets:`](/config/constants-secrets-lists#secrets) are log-redacted.
* Delivery goes through rflow's own senders (telegram / slack / discord) — no
  third-party relay.
* The step output is `{ "channel": "...", "status": <http status> }`.
* Delivery failures follow normal step failure handling: 5xx/timeouts are retryable
  under a `retry:` block; a bad token or webhook is terminal.

### Pattern: alert-only workflows

Monitoring needs no signer and no relayer — an event trigger plus `notify` is a
complete project:

```yaml
workflows:
  large-transfers:
    trigger:
      event:
        contract: USDC
        name: Transfer
        network: ethereum
        where: "${{ trigger.args.value > wei('1000000', 6) }}"
    steps:
      - id: alert
        notify:
          channel: ops
          message: "🚨 ${{ format_units(trigger.args.value, 6) }} USDC from ${{ trigger.args.from }}"
```


## query

Read-only SQL over the project's **indexed event tables** (and the rflow
journal) — decisions over history, not just the triggering event. With
`assert:` it becomes a hard gate; without, it's enrichment for later steps.

```yaml
- id: gate
  query:
    sql: >-
      SELECT COALESCE(SUM(value::numeric), 0)
      FROM rflow_indexer_rflow_idx_usdc.transfer
      WHERE lower("to") = lower($1)
        AND block_timestamp > now() - interval '1 day'
    args: ["${{ constants.vault }}"]
    assert: "${{ output < wei('1000000', 6) }}"   # daily inflow cap
```

### Fields

| Field      | Required | Description                                                                                             |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `sql`      | ✅        | ONE read-only statement: `SELECT` or `WITH … SELECT`                                                    |
| `args`     |          | `$1..$N` values — each may be an [expression](/workflows/expressions) over the full run context         |
| `assert`   |          | Expression over the shaped `output` (alias `result`) — false fails the step with kind `assert_failed`   |
| `on_error` | `fail`   | `continue` turns a failed query (timeout, SQL error) into `output: null`; a false `assert:` still gates |
| `timeout`  | `5s`     | Postgres `statement_timeout` for this statement                                                         |

### Where the data lives — the table naming rule

rflow's embedded indexer writes decoded event rows to Postgres with fully
deterministic names:

| Source                                                                                  | Schema.table                                 |
| --------------------------------------------------------------------------------------- | -------------------------------------------- |
| An **event trigger** on workflow `<wf>`                                                 | `rflow_indexer_rflow_<wf>.<event>`           |
| [`contracts.<name>.index_events`](/config/contracts#index_events--index-only-analytics) | `rflow_indexer_rflow_idx_<contract>.<event>` |
| The rflow journal (runs, steps, approvals, …)                                           | `rflow.*`                                    |

Workflow/contract names are lowercased with hyphens → underscores; event
names are snake-cased (`PoolCreated` → `pool_created`). Don't memorize it —
**`rflow tables`** prints the live catalog with columns and row counts:

```bash
$ rflow tables
table                                        columns                              rows
rflow_indexer_rflow_idx_usdc.transfer        rindexer_id, contract_address, ...   3214
rflow.workflow_runs                          id, workflow_name, trigger_key, ...    87
```

Every event table carries the decoded params as columns plus the indexer's
injected columns: `contract_address`, `tx_hash`, `block_number`,
`block_timestamp`, `block_hash`, `network`, `tx_index`, `log_index`.

### Column types & U256 exactness

The indexer's column mapping keeps big integers exact:

* ints up to 128 bits → `NUMERIC`
* **larger ints — including `uint256` amounts — → `VARCHAR(78)`** holding the
  exact decimal string. Aggregate or compare through a cast:
  `SUM(value::numeric)`, `value::numeric > $1`
* addresses → `CHAR(42)` lowercase hex — compare with
  `lower("to") = lower($1)` and quote the reserved column names (`"from"`,
  `"to"`)

`NUMERIC` results decode as exact decimal strings and cross into
`assert:`/`condition:` expressions as exact numbers — U256 comparisons like
`output >= wei('5', 18)` are precise, never floats. See
[U256 semantics](/workflows/expressions#u256-math-is-strict).

### Output shaping

The result set becomes `steps.<id>.output`:

* 1 row × 1 column → the scalar itself (the common aggregate case)
* 1 row × N columns → an object keyed by column name
* N rows → an array of objects, capped at 1000 rows — over the cap the value
  becomes `{ "rows": [...], "truncated": true }` and a warning logs.
  Aggregate in SQL instead of fetching raw rows.

### Injection guard

`${{ }}` inside `sql:` is a **hard validation error**. Dynamic values go
through `args:`, which bind as `$1..$N` parameters — never spliced into the
SQL text. On top of the textual read-only gate (single statement, no
data-modifying keywords, `WITH d AS (DELETE …)` rejected), every query runs
inside a Postgres `READ ONLY` transaction, so writes are refused by the
database itself.

```yaml
# ✗ rflow validate error — templating inside sql:
sql: "SELECT sum(value) FROM t WHERE \"to\" = '${{ trigger.args.to }}'"

# ✓ bind it
sql: SELECT sum(value::numeric) FROM rflow_indexer_rflow_idx_usdc.transfer WHERE "to" = $1
args: ["${{ trigger.args.to }}"]
```

### assert — the gate

A false `assert:` fails the step with kind `assert_failed` — a deliberate
stop, never retried; the run follows
[`on_failure`](/workflows#failure-handling). A fired `timeout` maps to the
`timeout` failure kind; other query failures are `data_unavailable`.

To fire a workflow FROM an aggregate instead of gating inside one, see the
[query trigger](/workflows/triggers/query).

### Timing honesty

Rows appear in the event tables when the indexer processes the block —
milliseconds behind head in steady state, further behind during backfill. A
`query:` step in a workflow triggered by the very event it aggregates may or
may not see that event's own row; anchor thresholds so off-by-one-event does
not matter, or aggregate over explicitly closed windows
(`block_number <= $2` with `args: [..., "${{ trigger.block_number - 1 }}"]`).


## read

`eth_call` a view function. With `assert:` it becomes a hard gate; without, it's
enrichment for later steps.

```yaml
- id: gate
  read:
    contract: USDC
    network: base
    function: "balanceOf(address)"
    args: ["${{ relayers.payout.address }}"]
    assert: "${{ output >= trigger.args.value }}"
```

### Fields

| Field      | Required | Description                                                                           |
| ---------- | -------- | ------------------------------------------------------------------------------------- |
| `contract` | ✅        | A [contract registry](/config/contracts) name                                         |
| `network`  | ✅        | A declared [network](/config/networks)                                                |
| `function` | ✅        | Solidity signature, e.g. `balanceOf(address)`                                         |
| `args`     |          | Arguments — each may be an [expression](/workflows/expressions)                       |
| `assert`   |          | Expression over the decoded `output` — false fails the step with kind `assert_failed` |
| `on_error` | `fail`   | `fail` \| `continue` — see below                                                      |

### Output

The decoded return values become `steps.<id>.output`:

* a single return value is unwrapped: `balanceOf` → `steps.gate.output` is the
  balance itself
* multiple return values become a map keyed by ABI output names (positional when
  unnamed)

`uint256` outputs stay exact — compare and do math on them directly, see
[U256 semantics](/workflows/expressions#u256-math-is-strict).

### assert — the gate

The `assert:` expression sees `output` alongside the full run context:

```yaml
assert: "${{ output >= trigger.args.value and output > wei('1', 6) }}"
```

A false assert fails the step with kind `assert_failed` — a deliberate stop, never
retried. The run then follows [`on_failure`](/workflows#failure-handling).

### on\_error: continue — soft enrichment

By default a failed read (RPC error, revert, false assert) fails the step. Set
`on_error: continue` to turn it into soft enrichment instead: the step succeeds with
`output: null` and the run continues.

```yaml
- id: price
  read:
    contract: Oracle
    network: ethereum
    function: "latestAnswer()"
    on_error: continue     # nice-to-have, not load-bearing
```


## send\_transaction

Queue a transaction through the embedded relayer.

```yaml
- id: mirror
  send_transaction:
    network: base
    relayer: payout
    contract: USDC
    function: "transfer(address,uint256)"
    args: ["${{ contracts.Treasury.address }}", "${{ trigger.args.value }}"]
    valid_for: 5m
    wait_for: confirmed
    gas: { max_price: 100 gwei, max_cost: 0.01 ether }
    assert_sim: ["${{ sim.gas_used < 500000 }}"]
  retry:
    max_attempts: 3
    retry_if: "${{ error.kind in ['rpc_timeout', 'rate_limited', 'gas_cap_exceeded'] }}"
```

### Fields

| Field                | Required    | Description                                                                                                                                                                               |
| -------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network`            | ✅           | A declared [network](/config/networks) — this is how cross-chain works: trigger on one, send on another                                                                                   |
| `relayer`            | ✅           | A named [relayer](/config/relayers) to send from                                                                                                                                          |
| `contract`           | one of      | Target: a [contract registry](/config/contracts) name...                                                                                                                                  |
| `to`                 | one of      | ...or a raw `0x` address (no registry entry needed)                                                                                                                                       |
| `function`           |             | Solidity signature, e.g. `transfer(address,uint256)`                                                                                                                                      |
| `args`               |             | Arguments — each may be an [expression](/workflows/expressions)                                                                                                                           |
| `value`              |             | Native value to attach — unit literals work: `0.1 ether`, or `"${{ wei('0.1', 18) }}"`                                                                                                    |
| `data`               |             | Raw calldata alternative to `function`/`args`                                                                                                                                             |
| `simulate`           | `true`      | Pre-flight simulation — see below                                                                                                                                                         |
| `on_simulation_fail` | `abort`     | `abort` \| `skip` \| `continue` \| `notify`                                                                                                                                               |
| `assert_sim`         |             | Assertions over the simulation result (`sim.*`) — see below                                                                                                                               |
| `gas`                |             | Client-side gas guardrails — see below                                                                                                                                                    |
| `recheck`            |             | Expression re-evaluated immediately before broadcast — see below                                                                                                                          |
| `valid_for`          |             | Expiry for queued sends, e.g. `5m` — a stale send never fires late                                                                                                                        |
| `wait_for`           | `confirmed` | `none` \| `submitted` \| `included` \| `confirmed` \| `confirmed(N)` \| `finalized` — see below                                                                                           |
| `speed`              | relayer's   | Override the relayer's speed for this send: `SLOW` \| `MEDIUM` \| `FAST` \| `SUPER`                                                                                                       |
| `approval`           |             | Human gate on the prepared transaction: a single `via:` gate, a named N-of-M `policy:`, or ordered `when:` tiers (`value` = the send's native value in wei) — see [Approvals](/approvals) |
| `propose_to_safe`    |             | PROPOSE to a Safe (delegate-signed, via the Transaction Service) instead of broadcasting — see [Safe proposal mode](/approvals#safe-proposal-mode)                                        |
| `multicall`          |             | N calls in one transaction via Multicall3 — see below                                                                                                                                     |

### Simulation is the default

Every send is pre-flight simulated (`eth_call` with the exact calldata) before it is
queued. A revert is decoded — custom errors included — into `steps.<id>.error` and
the step aborts. You only write `simulate: false` or `on_simulation_fail:` to change
that behavior:

* `abort` *(default)* — the step fails with kind `simulation_failed`
* `skip` — the step is skipped, the run continues
* `continue` — send anyway (you probably don't want this)
* `notify` — intended to skip-and-surface; **today it still aborts the step
  with a warning** (the notify path lands in a later phase — documented so you
  are not surprised)

### assert\_sim — gates over the simulation

`assert_sim:` expressions run after the simulation and see a `sim` root:

```yaml
assert_sim:
  - "${{ sim.ok }}"
  - "${{ sim.gas_used < 500000 }}"
```

| Path              | Description                     |
| ----------------- | ------------------------------- |
| `sim.ok`          | The call succeeded              |
| `sim.gas_used`    | From `eth_estimateGas`          |
| `sim.return_data` | The raw return bytes (`0x`-hex) |

Any false assertion aborts the step **before broadcast** with kind
`assert_failed` — a deliberate gate, never retried.

### gas — client-side guardrails

```yaml
gas:
  max_price: 100 gwei        # abort if eth_gasPrice is above this
  max_cost: 0.01 ether       # abort if projected limit × price is above this
  limit: 500000              # the limit used by the max_cost projection
  limit_from_simulation: true  # ...or derive it from eth_estimateGas
  multiplier: 1.2            # applied to the estimated limit (default 1.2)
```

:::warning
These are **client-side, pre-queue guardrails** — rflow checks them before the
transaction is handed to the embedded relayer. Once queued, rrelayer owns gas
estimation, bidding and bumping (its send request takes no gas limit). The same
is true of [`relayers.<name>.policy`](/config/relayers): `max_gas_price` and
`whitelist_receivers` are enforced by rflow before queueing, not spliced into
the relayer engine.
:::

A tripped cap fails the step with kind `gas_cap_exceeded` — **retryable**, since
gas prices fall: a `retry:` with `backoff:` legitimately waits a spike out.

### recheck — don't fire stale

`recheck:` is re-evaluated **immediately before broadcast** — after approval
waits, queue delays, retries — against the current context. False means the send
is dropped rather than fired stale:

```yaml
recheck: "${{ now() - trigger.block_number * 12 < duration('10m') }}"
```

Pair it with [`approval:`](/approvals) — conditions can change while a human
decides.

### multicall — N calls, one transaction

```yaml
- id: harvest-all
  send_transaction:
    network: ethereum
    relayer: keeper
    multicall:
      - { contract: VaultA, function: "harvest()" }
      - { contract: VaultB, function: "harvest()" }
      - { contract: VaultC, function: "compound(uint256)", args: ["${{ steps.plan.output }}"] }
```

Batches every call into a single Multicall3 `aggregate3` transaction. Mutually
exclusive with `contract`/`to`/`function`/`data` (validated).

:::warning
Inside the batched calls, `msg.sender` is the **Multicall3 contract**, not your
relayer — access-controlled functions will see the wrong caller. Relatedly, a
`whitelist_receivers` policy checks the transaction's final `to`, which for a
multicall is the Multicall3 address (the error message says so).
:::

### wait\_for

What the step waits for before the next step runs:

| Target                     | Meaning                                                                                                                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none`                     | Fire and forget — the step succeeds once queued. Consecutive `wait_for: none` sends are nonce-ordered by the relayer and land back-to-back                                                                                |
| `submitted`                | In the mempool                                                                                                                                                                                                            |
| `included` (alias `mined`) | In a block                                                                                                                                                                                                                |
| `confirmed` *(default)*    | At the network's [confirmations](/config/networks#core-fields) depth (default 12) — later steps can rely on `steps.<id>.receipt`                                                                                          |
| `confirmed(N)`             | An explicit depth. `N` at or below the network's relayer depth settles at the relayer's CONFIRMED (never shallower); `N` above it makes rflow verify the chain itself — polling head until the receipt is `N` blocks deep |
| `finalized`                | Real finality: rflow polls `eth_getBlockByNumber('finalized')` until the finalized block reaches the receipt block — not a confirmation-count proxy                                                                       |

While waiting, the run parks durably (`waiting_tx`) — a restart resumes the wait, it
never re-sends.

(For waiting on *someone else's* event — cross-chain sagas — see the
[`wait_for:` step](/workflows/steps/wait-for), a different construct.)

### What later steps see

| Path                                     | Description                                                                                                                                                  |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `steps.<id>.tx.hash`                     | Transaction hash                                                                                                                                             |
| `steps.<id>.tx_id`                       | Stable relayer id — **survives gas-bump hash changes**; prefer it for bookkeeping                                                                            |
| `steps.<id>.receipt`                     | The receipt, once mined (with `wait_for: included`+)                                                                                                         |
| `steps.<id>.output.value`                | The native value the send attached (wei, as a decimal string) — journaled, so spend reports can aggregate `output->>'value'` straight from `rflow.step_runs` |
| `steps.<id>.status` / `steps.<id>.error` | Step outcome                                                                                                                                                 |

### Failure semantics — who owns what

rflow owns everything **before** the queue: simulation, `assert_sim`, gas caps,
relayer policy checks, encoding, `recheck`, expiry (`valid_for`), approval gates,
and retries of pre-queue failures (`rpc_timeout`, `rate_limited`,
`gas_cap_exceeded`).

The relayer owns everything **after**: nonce management, gas pricing, gas bumping,
rebroadcast, stuck-tx replacement. rflow never re-implements these and never
blind-retries a transaction that made it onchain and reverted — a reverted tx is a
step failure (kind `reverted`) routed to [`on_failure`](/workflows#failure-handling).

Every send carries a client-side idempotency key journaled *before* the request, so
a crash between "sent" and "recorded" is resolved by lookup, not by re-sending. The
full story: [Reliability](/reliability).


## state\_set, list\_add & list\_remove

Three small steps that give workflows durable memory: a Postgres-backed
key/value store (`state_set`) and runtime mutation of your
[`lists:`](/config/constants-secrets-lists#lists) watchlists
(`list_add` / `list_remove`). Plus the `previous_run` context root for
comparing against the last run.

### state\_set

```yaml
steps:
  - id: read-price
    read: { contract: Oracle, network: ethereum, function: "latestAnswer()" }
  - id: alert-on-move
    if: "${{ state['oracle.last_price'] is defined and mul_div(steps.read-price.output, 100, state['oracle.last_price']) > 105 }}"
    notify: { channel: ops, message: "price moved >5% since the last tick" }
  - id: remember
    state_set:
      key: "oracle.last_price"
      value: "${{ steps.read-price.output }}"
```

| Field   | Description                                          |
| ------- | ---------------------------------------------------- |
| `key`   | The state key — may be an expression                 |
| `value` | The value — may be an expression; numbers stay exact |

Values persist in `rflow.state` and are readable from any expression as
`state.<key>` (or `state['dotted.key']`). State written earlier **in the same
run** is visible to the next step's expressions.

:::warning
State keys are **global across workflows** — there is no per-workflow
namespace. Namespace by convention: `<workflow>.<key>` (as above). A key that
was never set is strictly undefined — guard first reads with `is defined`.
The `state.*` expression root is capped at the first 1000 keys (by key order,
with a loud warning) — it is working memory, not a database.
:::

### list\_add / list\_remove

```yaml
lists:
  blocked: { seed: [] }

workflows:
  auto-block:
    trigger:
      event: { contract: AnyPool, name: Swap, network: ethereum, ... }
    steps:
      - id: block-trader
        if: "${{ trigger.args.amount0 > wei('1000000', 18) }}"
        list_add:
          list: blocked
          value: "${{ trigger.args.sender }}"
```

| Field   | Description                                                        |
| ------- | ------------------------------------------------------------------ |
| `list`  | A list declared under `lists:` (validated)                         |
| `value` | The member — may be an expression; addresses are stored lowercased |

The classic factory pattern: one workflow watches `PoolCreated` and
`list_add`s each child; other workflows filter with
`${{ trigger.address in lists.pools }}`.

#### What a list *is* at runtime

`lists.<name>` in expressions is the **union** of three provenances (visible
with `rflow list show`):

| Provenance | Written by                                                                               | Removed by                                                   |
| ---------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `seed`     | `rflow.yaml`                                                                             | editing `rflow.yaml` (`list_remove`/CLI cannot remove seeds) |
| `manual`   | [`rflow list add`](/cli#rflow-list)                                                      | `rflow list remove` / `list_remove:`                         |
| `workflow` | `list_add:` steps                                                                        | `list_remove:` / CLI                                         |
| `source`   | [`lists.<name>.source`](/config/constants-secrets-lists#source--http--sql--file) refresh | the next refresh (atomically replaced)                       |

A mutation is visible to the very next `where:` evaluation — no restart needed.

### previous\_run — compare against last time

Every step expression can read the workflow's **last succeeded run**:

| Path                                      | Description                            |
| ----------------------------------------- | -------------------------------------- |
| `previous_run.id` / `previous_run.status` | The run (status is always `succeeded`) |
| `previous_run.steps.<id>.output`          | That run's journaled step output       |
| `previous_run.steps.<id>.status`          | That step's terminal status            |

```yaml
steps:
  - id: fetch
    http_call: { url: "https://api.example.com/rate" }
  - id: only-on-change
    if: "${{ previous_run.steps.fetch.output.body.rate != steps.fetch.output.body.rate }}"
    notify: { channel: ops, message: "rate changed: ${{ steps.fetch.output.body.rate }}" }
```

On the workflow's **first** run, `previous_run` is undefined — strict evaluation
makes an unguarded reference a step error (never a silent `false`). Guard it:

```yaml
if: "${{ previous_run is not defined or previous_run.steps.fetch.output.body.rate != steps.fetch.output.body.rate }}"
```

### Dry-run behaviour

In [`rflow replay` / `rflow test`](/backtesting) sessions, `state_set` /
`list_add` / `list_remove` **skip their writes** and journal `would_set` /
`would_mutate` outputs instead — reads see live state, writes never land, and
there is nothing to clean up after a rehearsal.


## wait\_for

Park the run — durably — until the **first** of several conditions. This is the
cross-chain saga construct: send on chain A, wait for the matching event on
chain B, continue (or compensate on timeout).

```yaml
workflows:
  bridge-and-sweep:
    trigger:
      event: { contract: Bridge, name: DepositInitiated, network: ethereum, confirmations: 20 }
    steps:
      - id: send-l2
        send_transaction: { network: base, relayer: payout, ... }
      - id: await-arrival
        wait_for:
          any:
            - event:
                contract: BridgeReceiver
                network: base
                name: DepositFinalized
                where: "${{ trigger.args.depositId == 12345 }}"
            - timeout: 30m
          on_timeout: { goto: { step: compensate } }   # or: fail | continue
      - id: sweep
        send_transaction: { ... }
      - id: compensate
        if: "${{ steps.await-arrival.output.timed_out is defined }}"
        notify: { channel: ops, message: "bridge deposit did not arrive in 30m" }
```

| Field        | Required | Description                                                                                             |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `any`        | ✅        | Conditions raced against each other (non-empty, validated): `event: {...}` and/or `timeout: <duration>` |
| `on_timeout` | `fail`   | What a winning `timeout:` does — `fail` \| `continue` \| `goto: { step: <id> }`                         |

### The awaited event

`any: - event:` takes `contract` (registry name), `network`, `name`, an
optional `where:` and an optional `confirmations:`. **Inside the wait's
`where:` expression, `trigger.*` refers to the awaited event** — its args and
envelope — not the run's original trigger. No other root (`steps.*`,
`state.*`, `constants.*`, `item`, ...) exists at match time, so bind concrete
values into the expression via the surrounding YAML where you can.
`rflow validate` enforces this: a `where:` referencing anything besides
`trigger.*` can never match, so it is a hard error when the wait has no
`timeout:` condition (the run would park forever) and an Advice when it has
one.

A match settles the step `succeeded` with the decoded event as
`steps.<id>.output`; on an `on_timeout: continue`/`goto`, the output is
`{"timed_out": true}`.

#### `confirmations:` — how deep before the wait settles

| Value            | Behaviour                                                                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| absent (default) | A *confirmed* delivery settles the wait immediately; a head delivery only ARMS it — the parked run then settles once the chain reaches the network's `confirmations` depth past the event |
| `0`              | Settle the moment the event is first seen (head). `rflow validate` prints a reorg Advice when the workflow sends transactions                                                             |
| `N`              | The match is journaled (armed) and the wait settles once the event is `N` blocks deep (verified against the chain, like a send's `confirmed(N)`)                                          |
| `finalized`      | Armed until the chain's finalized block reaches the event (`rflow doctor` probes finality support; validate advises on chains rflow has no guidance for)                                  |

### Internal wait subscriptions

Every `wait_for:` event condition gets its own indexer subscription: at boot,
manifest generation collects the `(contract, event, network)` triples across
all workflows (main steps, `foreach` bodies and `finally:` blocks) and
subscribes to any triple no declared event trigger already feeds the wait
matcher for. Only a trigger's **confirmed** phase feeds the matcher
(`run_on: confirmed` — the default — or `both`); a head-only
`run_on: unconfirmed` trigger covers nothing, and a `confirmations: 0` wait
always gets its own head-indexing subscription — no trigger path delivers
head fires to the matcher. These wait-only subscriptions route decoded
events **only** to the wait matcher — they never create runs — and they
start at the **latest** block: they exist to catch future events while a run
is parked, never to backfill history. A contract declared on exactly **one**
network resolves for waits on any network: the subscription indexes that
single address on the awaited chain (the same fallback validate and the
engine apply).

`rflow validate` rejects impossible waits before runtime: an awaited event
missing from the contract's ABI (with a did-you-mean hint), an unknown
contract/network, a wait whose contract has **no address on the awaited
network** *and* no `timeout:` condition (it would park forever — with a
timeout it degrades to an Advice), and a `where:` that references anything
besides `trigger.*` (same error/Advice split).

### Durability

Every event condition is persisted (`rflow.run_event_waits`, including its
`confirmations` requirement and any armed match) and the timeout deadline is
journaled **before** the run parks (`waiting_event`) — all survive restarts,
and a parked saga costs nothing while it waits. The `goto:` decision is part
of the settle output, so a crash right after a timeout-goto resumes at the
**same named step** — crash-resume is exact, not just journal-order. A goto
that re-enters a `foreach:` step starts a **fresh pass**: the collection is
re-evaluated and every iteration re-runs with fresh attempt numbers (fresh
send idempotency keys — the point of a fan-out/wait/re-do saga), while a
plain retry of a failed fan-out still reuses the pass's journaled plan and
never re-runs its settled iterations.

### Placement

`wait_for` also runs inside [`foreach`](/workflows#foreach--fan-a-step-out)
iterations — each item parks its own `<id>[<i>]` journal row and wait rows,
resumes independently and settles exactly once (a parked item holds its
`max_parallel` slot, like a long delay) — and inside
[`finally:`](/workflows#finally--always-run-steps) blocks, where the step
parks and resumes but the run's terminal status never changes (finally stays
best-effort across restarts). Two caveats: `on_timeout: goto` is rejected
inside `foreach`/`finally` (there is no step sequence to jump to), and the
match-time `where:` only sees `trigger.*`, so foreach items share their
conditions — one matching event settles every parked item it matches.

### Reorg safety

:::warning
A wait armed by a **head** delivery (`confirmations: 0`, or a default/depth
wait fed by a head-indexing wait-only subscription) verifies depth by chain
**height**, the same check a send's `confirmed(N)` beyond the relayer depth
uses — it does not re-prove the log's inclusion. Deliveries from confirmed
subscriptions are withheld by the indexer until they are reorg-safe. Prefer
the default behaviour (or an explicit depth) on money paths; `confirmations: 0`
trades reorg safety for latency and validate says so.
:::

### Dry-run behaviour

In [`rflow replay` / `rflow test`](/backtesting) sessions, `wait_for` steps
settle immediately with a `would_wait_for` output — a historical event must
never resume a live parked saga, and a rehearsal must terminate
deterministically. `--with-waits` pins deterministic per-step outcomes
(matched event or timeout) for saga rehearsals; fixtures key on the config
step id, so foreach items and finally waits resolve through their base id.


## Aave v3 health guardian

**Template:** `aave-health-guardian` · **category:** keeper · **risk:** `money_moving`

Guards an Aave v3 position from your own side. It polls
`getUserAccountData(position).healthFactor`; when it drops below a floor, it
approves the Pool for the debt asset and parks a `repay` behind a human
approval to restore health. A position with no debt reports `healthFactor =
uint256 max`, so it never trips.

### When to use it

* keep a leveraged position off the liquidation line automatically
* want a human to confirm each repay, with the live health factor in the message
* self-protect rather than liquidate others (see
  [`liquidation-keeper`](/use-cases/liquidation-keeper) for the other side)

### Generate it

```bash
rflow new --template aave-health-guardian

# or add the workflow to an existing project
rflow add workflow aave-health-guardian
```

Non-interactive (CI/agents):

```bash
rflow new --template aave-health-guardian --yes --output ./guardian \
  --answer min_health=1.05 --answer repay_amount=1000
```

### Inputs

| key                                                  | type                                    | default                                     |
| ---------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                       | string                                  | `aave-health-guardian`                      |
| `network` / `chain_id` / `rpc_env` / `rpc_url`       | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `confirmations`                                      | int                                     | `3`                                         |
| `pool_name` / `pool_address`                         | contract / address                      | `Pool` / zero placeholder (replace!)        |
| `debt_name` / `debt_asset_address` / `debt_decimals` | contract / address / int                | `DebtAsset` / USDC mainnet / `6`            |
| `position`                                           | address                                 | zero placeholder (replace!)                 |
| `min_health` / `health_decimals`                     | token\_amount / int                     | `1.05` / `18`                               |
| `repay_amount` / `rate_mode`                         | token\_amount / int                     | `1000` / `2`                                |
| `poll_every` / `approval_timeout`                    | duration                                | `30s` / `15m`                               |
| `gas_max_price`                                      | string                                  | `60 gwei`                                   |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), and
`RAW_DANGEROUS_MNEMONIC` — `rflow new` writes a fresh DEV-ONLY mnemonic;
swap in a production signer before real funds ride on it.

### Safety notes

Money-moving, so every rail is on: pre-flight simulation with
`assert_sim: ["${{ sim.ok }}"]` on both the `approve` and the `repay`, a
`gas.max_price` ceiling, a concurrency group (`skip`), `wait_for: confirmed`
and `on_failure: dead_letter`. The `repay` is parked behind
[approval](/approvals) — `rflow approve <id>` — and re-simulates immediately
before broadcast. The health test is edge-triggered, so a position sitting
under the floor does not re-fire every poll. Attach a
[budget](/workflows/budgets) to cap cumulative repay spend.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + a real signer), set pool/debt/position
rflow validate
rflow start
```

### Common modifications

* swap `repay` for `supply` (add collateral) — same shape, different function
* lower `poll_every` and widen `min_health` for tighter guarding
* pre-approve the Pool once and drop the `approve` step


## Bridge message watch

**Template:** `bridge-message-watch` · **category:** bridge-ops · **risk:** `monitor_only`

Delivery-liveness monitoring for a message bridge: watch `MessageSent` on the
source chain and `MessageReceived` on the destination chain, cross-referenced
by their shared `nonce` through rflow's durable
[state](/workflows/steps/state-and-lists). Every sent message starts a
durable delivery clock; when the clock runs out and no receipt marked the
nonce delivered, a channel gets paged. Two networks, no signer, no
transactions.

### When to use it

* you operate (or depend on) a bridge/messenger and want to know about stuck
  messages before your users do
* watch a canonical rollup messenger, a token bridge's send/receive pair, or
  any cross-chain protocol with a nonce-correlated send/receive event pair
* as the alerting layer next to your relayer infrastructure: a page here
  means "the relayer/prover is behind"

### Generate it

```bash
rflow new --template bridge-message-watch
# or into an existing project:
rflow add workflow bridge-message-watch
```

Non-interactive (CI/agents):

```bash
rflow new --template bridge-message-watch --yes --output ./bridge-watch \
  --answer source_bridge_address=0x8d3f4e2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e \
  --answer dest_bridge_address=0x1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d \
  --answer delivery_timeout=30m
```

### The generated YAML

Two workflows share one contract registry entry (same name, one address per
network):

```yaml
# recipe: partial
workflows:
  # source side: wait out the delivery window, then alert unless delivered
  bridge-message-watch:
    trigger:
      event:
        contract: Bridge
        name: MessageSent
        network: ethereum
        confirmations: 12
        start_block: latest
        end_block: live
    steps:
      - id: window
        delay: 30m                       # durable - survives restarts
      - id: alert
        if: "${{ state['bridge.delivered.' ~ trigger.args.nonce] is not defined }}"
        notify:
          channel: ops
          message: "bridge message nonce ${{ trigger.args.nonce }} sent on ethereum (${{ trigger.tx_hash }}) has NOT been received on base within 30m"
    on_failure: dead_letter

  # destination side: mark each delivered nonce - the cross-reference
  bridge-message-received:
    trigger:
      event:
        contract: Bridge
        name: MessageReceived
        network: base
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: mark
        state_set:
          key: "bridge.delivered.${{ trigger.args.nonce }}"
          value: "${{ trigger.tx_hash }}"
    on_failure: dead_letter
```

### Inputs

| key                                                                        | type                                    | default                                       |
| -------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------- |
| `project_name`                                                             | string                                  | `bridge-message-watch`                        |
| `source_network` / `source_chain_id` / `source_rpc_env` / `source_rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC   |
| `dest_network` / `dest_chain_id` / `dest_rpc_env` / `dest_rpc_url`         | network / chain\_id / env\_var / string | `base` / `8453` / `BASE_RPC` / a public RPC   |
| `bridge_name`                                                              | contract                                | `Bridge`                                      |
| `source_bridge_address` / `dest_bridge_address`                            | address                                 | **required**                                  |
| `confirmations`                                                            | int                                     | `12` — depth before the delivery clock starts |
| `delivery_timeout`                                                         | duration                                | `30m`                                         |
| `channel`                                                                  | string                                  | `ops`                                         |

### Required env vars

`DATABASE_URL`, both RPC env vars (default `ETH_RPC` and `BASE_RPC`),
`TG_BOT_TOKEN`, `TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

* Monitor-only: two networks, no `signer:` — the relayer engine never boots.
* The `delay:` is **durable** (persisted wake-at): a restart mid-window does
  not lose the watch, and the parked run holds no executor permit.
* `confirmations: 12` on `MessageSent` keeps reorged sends from starting
  phantom clocks; receipts are marked at head (`confirmations: 0`) so a
  delivery is never counted late.
* Both workflows end in `on_failure: dead_letter` — a failed mark or page is
  parked and journaled, never lost.
* The packaged `abis/bridge.json` is a **generic** ABI. Real bridges name
  their events differently — swap in your bridge's ABI and adjust the two
  `name:` fields (and the `nonce` arg); `rflow validate` checks events
  against the ABI.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (both RPCs + telegram credentials)
rflow validate
rflow start
```

For a fast rehearsal on anvil: deploy any contract emitting the two events,
answer both networks to your fork, set `delivery_timeout=30s`, emit
`MessageSent` without the matching receive, and watch the alert land.
`fixtures/message-sent-event.json` documents the decoded trigger context the
check and the alert message render against.

### Production checklist

* [ ] `delivery_timeout` > the bridge's honest p99 delivery latency
  (including proving/challenge delays), or every slow-but-fine message
  pages
* [ ] `confirmations` matched to the source chain's reorg reality —
  [validate prints per-chain advice](/reorgs)
* [ ] destination RPC dependable: if the receive-side indexer stalls, unmarked
  nonces will page — add
  [indexer stall detection](/operations/unattended-ops#indexer-stall-detection)
* [ ] state is working memory (first-1000-keys cap on the `state.*` root, no
  state-delete step): on a high-volume bridge, cross-reference through a
  [`query:`](/workflows/steps/query) over the indexed `message_received`
  table by nonce instead
* [ ] pair with [`workflow-error-pager`](/use-cases/workflow-error-pager) so
  a dead-lettered watch run itself pages

### Common modifications

* **query instead of state** (unbounded volume): replace the `if:` guard
  with a `query:` step over
  `rflow_indexer_rflow_bridge_message_received.message_received` filtered by
  `nonce = $1`, and assert on the count
* page harder on misses: point the alert at a pagerduty channel
  (`rflow add notification`), keep telegram for receipts
* watch both directions: `rflow add workflow bridge-message-watch --name
  reverse --answer source_network=base ...` with the networks swapped
* alert on *failed* deliveries too: `MessageReceived` carries `success` in
  the generic ABI — add a second destination workflow with
  `where: "${{ trigger.args.success == false }}"`


## Chainlink deviation alert

**Template:** `chainlink-deviation-alert` · **category:** monitoring · **risk:** `monitor_only`

Compares two Chainlink price feeds on a schedule and pages when they disagree
by more than a basis-point threshold — a primary oracle vs a fallback, or two
oracles for the same asset. A disagreement is the signal a feed has frozen,
been manipulated, or a fallback is drifting.

### When to use it

* cross-check the oracle your protocol relies on against a second source
* catch a stuck/laggy feed before it prices a liquidation wrong
* watch a fallback oracle drift away from the primary

### Generate it

```bash
rflow new --template chainlink-deviation-alert

# or add the workflow to an existing project
rflow add workflow chainlink-deviation-alert
```

Non-interactive (CI/agents):

```bash
rflow new --template chainlink-deviation-alert --yes --output ./deviation \
  --answer deviation_bps=50
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `chainlink-deviation-alert`                 |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `feed_a_name` / `feed_a_address`               | contract / address                      | `FeedA` / zero placeholder (replace!)       |
| `feed_b_name` / `feed_b_address`               | contract / address                      | `FeedB` / zero placeholder (replace!)       |
| `feed_decimals`                                | int                                     | `8`                                         |
| `deviation_bps`                                | int                                     | `50`                                        |
| `poll_cron`                                    | cron                                    | `*/5 * * * *`                               |
| `channel`                                      | string                                  | `ops`                                       |

Deviation is `|a - b| * 10000 / min(a, b)` basis points (100 bps = 1%),
computed with `mul_div` in full precision. Both feeds must be **positive** and
share the same `decimals` (true for same-asset USD feeds, which are 8).

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The trigger is a cron, so a persistent gap **re-alerts every tick** —
widen `poll_cron` or add a dedupe list if that is too chatty (a two-feed
comparison can't use the read trigger's edge-triggered mode). The workflow
ends in `on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, set both feed addresses
rflow validate
rflow start
```

### Common modifications

* tighten `deviation_bps` to page on smaller disagreements
* compare a Chainlink feed against a DEX TWAP by swapping one contract
* widen `poll_cron` to cut RPC load


## Chainlink oracle staleness

**Template:** `chainlink-oracle-staleness` · **category:** monitoring · **risk:** `monitor_only`

Polls a Chainlink aggregator's `latestRoundData()` on an interval and alerts
when `updatedAt` is older than the feed's heartbeat — the classic "oracle went
quiet" alert every protocol that consumes a price feed should run. Firing is
edge-triggered: a stale feed alerts **once per episode**, then re-arms when
the feed updates again.

### When to use it

* your protocol prices collateral, liquidations, or redemptions off a feed
* you consume a low-activity feed on an L2 and want to know when it stalls
* as an early-warning input to a circuit breaker or pause policy

### Generate it

```bash
rflow new --template chainlink-oracle-staleness
# or add the workflow to an existing project:
rflow add workflow chainlink-oracle-staleness
```

Non-interactive (CI/agents):

```bash
rflow new --template chainlink-oracle-staleness --yes --output ./oracle-watch \
  --answer feed_address=0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419 --answer max_staleness=1h
```

### The generated workflow

```yaml
# recipe: partial
workflows:
  oracle-staleness:
    trigger:
      # poll latestRoundData() and fire on the false->true CROSSING of the
      # staleness condition (edge-triggered - a stale feed alerts once, not
      # every poll; it re-arms when the feed updates again)
      read:
        contract: EthUsdFeed
        network: ethereum
        function: "latestRoundData()"
        every: 2m
        condition: "${{ now() - output.updatedAt > duration('1h') }}"
        mode: threshold
    steps:
      - id: alert
        notify:
          channel: ops
          message: "ORACLE STALE: EthUsdFeed has not updated for over 1h (updatedAt ${{ trigger.args.output.updatedAt }}, answer ${{ format_units(trigger.args.output.answer, 8) }})"
    on_failure: dead_letter
```

`latestRoundData()` returns five values, so the decoded
[read output](/workflows/steps/read#output) is a map — the condition reads
`output.updatedAt`, the message reads `trigger.args.output.answer`.

### Inputs

| key                                            | type                                    | default                                      |
| ---------------------------------------------- | --------------------------------------- | -------------------------------------------- |
| `project_name`                                 | string                                  | `chainlink-oracle-staleness`                 |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC  |
| `feed_name` / `feed_address`                   | contract / address                      | mainnet ETH/USD (`0x5f4e…8419`)              |
| `feed_decimals`                                | int                                     | `8` (USD pairs; ETH pairs use 18)            |
| `max_staleness`                                | duration                                | `1h` — match the feed's documented heartbeat |
| `poll_every`                                   | duration                                | `2m`                                         |
| `channel`                                      | string                                  | `ops`                                        |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:`, no `relayers:`, no transactions. Set
`max_staleness` a little **above** the feed's heartbeat (heartbeat 1h → alert
at 1h5m if you want zero false positives; the default `1h` alerts the moment a
heartbeat is missed). The edge state is persisted in Postgres, so a restart
mid-staleness does not re-alert. `on_failure: dead_letter` journals failed
notifications.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + telegram credentials)
rflow validate
rflow start
```

Rehearse with a canned stale round (dry-run, nothing sent):

```bash
rflow test oracle-staleness --fixture fixtures/stale-round.json
```

### Production checklist

* [ ] `feed_address` is the **aggregator proxy** for your pair/network (see
  Chainlink's feed registry) and `feed_decimals` matches
* [ ] `max_staleness` is aligned with that feed's documented heartbeat
* [ ] `poll_every` is meaningfully shorter than `max_staleness`
* [ ] your RPC allows the poll rate you configured
* [ ] telegram credentials in `.env`, test with `rflow test`
* [ ] `rflow validate --preflight` passes against your RPC

### Common modifications

* also alert on price deviation: add a second read-triggered workflow with
  `mode: changed`, or compare against
  [`previous_run`](/workflows/steps/state-and-lists#previous_run--compare-against-last-time)
* watch several feeds: one `contracts:` entry + one workflow per feed
* feed a [circuit breaker](/reliability): let the alert `state_set` a flag
  your money-moving workflows check in a `recheck:` expression
* page instead of chat: swap the channel for pagerduty with
  `rflow add notification`


## Command decision

**Template:** `command-decision` · **category:** examples · **risk:** `monitor_only`

A cron reads a token's `totalSupply()` on-chain, a project-owned node script
**decides** a severity band, and rflow POSTs the decision to an HTTP endpoint
(HMAC-signed), escalating non-ok severities to a second endpoint. This is the
canonical `command:` step shape: rflow reads the chain, runs the step durably
and makes every HTTP call; your script reads JSON on stdin and prints one JSON
decision on stdout — no signing, no sending, no RPC handle. Runnable sibling:
[`examples/command-decision`](https://github.com/joshstevens19/rflow/tree/master/examples/command-decision).

### When to use it

* put YOUR risk logic (any language, here node) inside a durable rflow workflow
* classify an on-chain reading into bands and branch later steps on the result
* the starting point for command-driven monitors: swap `totalSupply()` for any
  view function and `decide.js` for your rule

### Generate it

```bash
rflow new --template command-decision
# or into an existing project:
rflow add workflow command-decision
```

### Inputs

| key                                               | type                                    | default                                     |
| ------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                    | string                                  | `command-decision`                          |
| `network` / `chain_id` / `rpc_env` / `rpc_url`    | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `token_name` / `token_address` / `token_decimals` | contract / address / int                | `USDC` / USDC mainnet / `6`                 |
| `check_cron`                                      | cron                                    | `*/15 * * * * *` (seconds field supported)  |
| `warn_supply` / `critical_supply`                 | token\_amount                           | `1000000` / `5000000` (whole tokens)        |
| `report_url` / `alert_url`                        | string                                  | `http://localhost:9098/report` / `/alert`   |
| `hmac_env`                                        | env\_var                                | `REPORT_HMAC_SECRET`                        |

### Generated YAML (the shape)

```yaml
# recipe: partial
steps:
  - id: supply          # rflow reads the chain
    read: { contract: USDC, function: "totalSupply()" }
  - id: decide          # your script decides
    command:
      run: "node ./scripts/decide.js"
      timeout: 10s
      output: json
      input: { supply: "${{ steps.supply.output }}", warn_above: "1000000", ... }
  - id: report          # always POSTed, HMAC-signed by rflow
    http_call: { url: ..., hmac: "${{ secrets.report_hmac }}", body: { severity: "${{ steps.decide.output.severity }}", ... } }
  - id: escalate        # later steps branch on what the command decided
    if: "${{ steps.decide.output.severity != 'ok' }}"
    http_call: { url: ..., ... }
on_failure: dead_letter
```

The thresholds travel through the `input:` map, so the rules are configured in
`rflow.yaml` and `scripts/decide.js` stays generic.

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), and the HMAC secret
(default `REPORT_HMAC_SECRET`) — all listed in the generated `.env.example`.
`node` must be on PATH for the decide step.

### Safety notes

Monitor-only: no signer, no relayer, no transactions — the workflow cannot
move money even if the script misbehaves. The script gets no secrets unless
you pass them via `command.env`, and its stdout is journaled, so keep secrets
out of the decision object. `on_failure: dead_letter` keeps failed runs
replayable.

### Run it locally

```bash
docker compose up -d
rflow validate
# rehearse without waiting for the cron:
rflow test command-decision --fixture fixtures/cron-tick.json
rflow start
```

### Production checklist

1. point `report_url` / `alert_url` at real sinks and rotate the HMAC secret
2. tune `warn_supply` / `critical_supply` to your token's real bands
3. slow `check_cron` down to something production-shaped (e.g. `*/5 * * * *`)
4. pin the node version your ops hosts run (`decide.js` uses BigInt — any
   supported node works, but pin it anyway)

### Common modifications

* swap `totalSupply()` for any view function (health factor, oracle price…)
* rewrite `decide.js` in any language — the stdin/stdout JSON contract is all
  that matters
* add a `notify:` step for human-visible escalations
* feed the decision into a `send_transaction:` step — see
  [`command-trade-prep`](/use-cases/command-trade-prep) for the money-moving
  version of this pattern


## Command trade prep

**Template:** `command-trade-prep` · **category:** relayers · **risk:** `money_moving`

A deposit into a watched address fires a project-owned node script that
**quotes** a trade (amount, min\_out, deadline, freshness window); rflow then
**signs, simulates, rechecks and sends** it. The quote script never signs or
sends — it has no private key and no RPC handle. Your logic decides *what* to
trade; rflow owns *moving the money*. Runnable sibling:
[`examples/command-trade-prep`](https://github.com/joshstevens19/rflow/tree/master/examples/command-trade-prep).

### When to use it

* keeper/trading flows where sizing lives in your own code or a pricing API
* any event-driven send whose parameters must be computed, not hardcoded
* the money-moving counterpart of [`command-decision`](/use-cases/command-decision)

### Generate it

```bash
rflow new --template command-trade-prep
# or into an existing project (needs a signer; adds the `trader` relayer):
rflow add workflow command-trade-prep
```

### Inputs

| key                                               | type                                    | default                                               |
| ------------------------------------------------- | --------------------------------------- | ----------------------------------------------------- |
| `project_name`                                    | string                                  | `command-trade-prep`                                  |
| `network` / `chain_id` / `rpc_env` / `rpc_url`    | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC           |
| `token_name` / `token_address` / `token_decimals` | contract / address / int                | `USDC` / USDC mainnet / `6`                           |
| `watched`                                         | address                                 | zero placeholder — **replace it**                     |
| `trade_target`                                    | address                                 | zero placeholder — **replace it**                     |
| `min_deposit`                                     | token\_amount                           | `100` (whole tokens)                                  |
| `confirmations`                                   | int                                     | `12` (blocks a deposit must be deep before it counts) |
| `quote_ttl`                                       | int                                     | `120` seconds                                         |
| `gas_max_cost`                                    | string                                  | `0.02 ether`                                          |

### Generated YAML (the shape)

```yaml
# recipe: partial
trigger:
  event:      # deposits >= min_deposit INTO the watched address
    contract: USDC
    name: Transfer
    where: "${{ trigger.args.value >= wei('100', 6) and lower(trigger.args.to) == lower(constants.watched) }}"
    confirmations: 12   # a reorged deposit can never trigger a trade
steps:
  - id: gate   # rflow reads the relayer's balance (the command never does)
    read: { function: "balanceOf(address)", args: ["${{ relayers.trader.address }}"] }
  - id: quote  # your script quotes: amount, min_out, deadline, valid_until
    command: { run: "node ./scripts/quote.js", timeout: 10s, output: json, ... }
  - id: trade  # rflow signs + simulates + rechecks + sends
    if: "${{ steps.quote.output.should_send == true }}"
    send_transaction:
      function: "transfer(address,uint256)"
      args: ["${{ constants.trade_target }}", "${{ steps.quote.output.amount }}"]
      simulate: true
      assert_sim: ["${{ sim.ok }}"]
      gas: { limit_from_simulation: true, multiplier: 1.2, max_cost: "0.02 ether" }
      recheck: "${{ now() < steps.quote.output.valid_until }}"
      wait_for: confirmed
on_failure: dead_letter
```

The 'trade' is modelled as an ERC20 `transfer` so the template is
self-contained; in a real deployment the same shape drives e.g.
`Router.swapExactTokensForTokens(...)` with the quoted min\_out/deadline/path
as args.

### Required env vars

`DATABASE_URL`, the RPC env var, `RAW_DANGEROUS_MNEMONIC`. `rflow new` fills
`.env` with a freshly generated DEV-ONLY mnemonic — swap in a production
signer before real funds ride on this config. `node` must be on PATH.

### Safety defaults (all generated)

* pre-flight simulation + `assert_sim: ["${{ sim.ok }}"]`
* gas cap: `limit_from_simulation` + `max_cost` — a fat-fingered price never drains gas
* `recheck: now() < valid_until` — a run parked/restarted past the quote's
  freshness window is **dropped, never broadcast stale**
* the trigger waits `confirmations: 12` before firing — a reorg cannot orphan
  the deposit AFTER the trade is sent
* `confirmations: 12` on the network, `wait_for: confirmed`
* `on_failure: dead_letter`

This path is **fully automated** (no approval gate — that would defeat a
trading keeper). If your flow can wait for a human, add an `approval:` block
to the trade step exactly as [`treasury-sweep-approval`](/use-cases/treasury-sweep-approval)
does.

### Run it locally

```bash
docker compose up -d
rflow validate
# rehearse without touching a chain (`to` in the fixture is your watched address):
rflow test command-trade-prep --fixture fixtures/deposit-event.json
rflow start
```

### Production checklist

1. replace the `watched` and `trade_target` zero placeholders
2. replace the raw dev mnemonic with a production signer
3. make `quote.js` call your real pricing source and enforce YOUR slippage
4. size `gas_max_cost` and `min_deposit` for the network you deploy on
5. add a spend budget / rate limit around the workflow when budgets exist in
   your project, and consider `concurrency:` if quotes must not overlap

### Common modifications

* drive a router/DEX call instead of `transfer` (use the quoted `min_out` and
  `deadline` as args)
* add an `approval:` gate for semi-automated desks
* `notify:` on every executed trade for a human audit trail
* tighten `quote_ttl` for fast markets — the recheck makes staleness a no-op


## Cron HTTP report

**Template:** `cron-http-report` · **category:** offchain · **risk:** `monitor_only`

A cron workflow POSTs an HMAC-signed JSON report to an HTTP endpoint on a
schedule. Pure off-chain: no networks and no signer, so neither embedded
engine boots. Runnable sibling:
[`examples/ops-monitor`](https://github.com/joshstevens19/rflow/tree/master/examples/ops-monitor).

### When to use it

* heartbeats into a status page, sink, or internal dashboard
* scheduled webhooks toward systems that verify an HMAC signature
* the smallest possible rflow project to learn the journal/run model on

### Generate it

```bash
rflow new --template cron-http-report
# or into an existing project:
rflow add workflow cron-http-report
```

### Inputs

| key            | type     | default                        |
| -------------- | -------- | ------------------------------ |
| `project_name` | string   | `cron-http-report`             |
| `report_cron`  | cron     | `*/5 * * * *`                  |
| `report_url`   | string   | `http://localhost:9099/report` |
| `report_name`  | string   | `heartbeat`                    |
| `hmac_env`     | env\_var | `REPORT_HMAC_SECRET`           |

### Required env vars

`DATABASE_URL` and the HMAC secret env var (default `REPORT_HMAC_SECRET`) —
listed in the generated `.env.example`. The secret signs every report body
(HMAC-SHA256) so the receiver can verify authenticity.

### Run it locally

```bash
docker compose up -d
rflow validate
rflow start
```

### Common modifications

* add an on-chain `read:` step before the report (see `examples/ops-monitor`)
* point `report_url` at a real sink and rotate the HMAC secret
* add `notify:` on top for human-visible heartbeats


## Cross-chain settlement saga

**Recipe** (no bundled template) · **category:** relayers · **risk:** `money_moving`

The canonical [`wait_for:` saga](/workflows/steps/wait-for): a user locks funds
in an escrow on the **source** chain (`OrderOpened`); you settle the recipient
on the **destination** chain; then the run **parks durably** until the source
escrow releases your repayment (`OrderSettled`) — or a timeout fires and you
**compensate** instead of silently double-paying. The payout is simulated,
gas-capped, `recheck`-guarded and behind a durable
[budget](/workflows/budgets).

Closest bundled starting points: the
[ERC-7683 intent solver](/use-cases/erc7683-solver) template (source event →
destination fill, same reorg discipline) and the
[bridge message watcher](/use-cases/bridge-message-watch) (the `state:`
cross-reference alternative to `wait_for`, described below).

### When to use it

* settle intents/orders where you pay on one chain and get repaid on another
* any "act on chain A, wait for the confirming event on chain B, else
  compensate" flow that must survive restarts while it waits
* bridge-and-continue flows that must not fire the second leg until the first
  is confirmed

### The config

`OrderOpened` on the source chain triggers a native settlement on the
destination chain; `wait_for:` then parks the run until the source escrow's
`OrderSettled` (or 30m), routing a timeout to a `compensate` step.

```yaml
# recipe: full
rflow_version: 1
name: cross-chain-settlement-saga

config:
  port: 3949
  db_connection: ${DATABASE_URL}
  max_concurrent_runs: 64

networks:
  # source: users lock funds in the escrow here
  - name: ethereum
    chain_id: 1
    rpc: ${ETH_RPC}
    confirmations: 12
  # destination: we settle to the recipient here
  - name: base
    chain_id: 8453
    rpc: ${BASE_RPC}
    confirmations: 6

# DEV ONLY raw mnemonic (from .env) - `rflow new` generates a fresh dev seed.
# Swap in a production signer before real funds ride on this config.
signer:
  raw:
    mnemonic: ${RAW_DANGEROUS_MNEMONIC}

relayers:
  # the settler wallet - pays recipients on the destination chain
  settler:
    networks: [base]
    speed: FAST

contracts:
  # the SOURCE-chain escrow: emits OrderOpened when a user locks funds and
  # OrderSettled when it releases our repayment after the settlement is proven
  Escrow:
    abi: ./abis/settlement.json
    addresses:
      ethereum: "0x1111111111111111111111111111111111111111"

budgets:
  # blast-radius cap on the destination payouts: at most 20 ETH/hour of
  # settlements no matter how many orders open
  settlement-hourly:
    window: 1h
    max_native_value: "20 ether"
    scope:
      relayers: [settler]
      networks: [base]

workflows:
  cross-chain-settlement:
    trigger:
      # a reorged open must never trigger a payout: fire only 12 blocks deep
      event:
        contract: Escrow
        name: OrderOpened
        network: ethereum
        confirmations: 12
        run_on: confirmed
        where: "${{ trigger.args.amount > wei('0', 18) }}"
    # one run per order id - concurrent opens of the same order are skipped
    concurrency:
      group: "settle-${{ trigger.args.orderId }}"
      on_conflict: skip
    budgets: [settlement-hourly]
    steps:
      # the money step, on the DESTINATION chain: pay the recipient natively.
      # Pre-flight simulated, gas-capped, dropped if the order's fill deadline
      # passed while we got here, then held until confirmed.
      - id: settle
        send_transaction:
          network: base
          relayer: settler
          to: "${{ trigger.args.recipient }}"
          value: "${{ trigger.args.amount }}"
          assert_sim:
            - "${{ sim.ok }}"
          gas:
            limit_from_simulation: true
            multiplier: 1.2
            max_price: "50 gwei"
          recheck: "${{ now() < trigger.args.fillDeadline }}"
          wait_for: confirmed
      # the async cross-chain leg: park - durably, for free - until the source
      # escrow releases our repayment, or 30m elapse and we compensate. Inside
      # the wait, trigger.* is the AWAITED OrderSettled event (see notes: pin a
      # concrete orderId literal when known, or cross-reference via state:).
      - id: release_wait
        wait_for:
          any:
            - event:
                contract: Escrow
                network: ethereum
                name: OrderSettled
                where: "${{ trigger.args.amount > wei('0', 18) }}"
                confirmations: 12
            - timeout: 30m
          on_timeout: { goto: { step: compensate } }
      - id: settled
        if: "${{ steps.release_wait.output.timed_out is not defined }}"
        notify:
          channel: ops
          message: "settled order ${{ trigger.args.orderId }} to ${{ trigger.args.recipient }} on base; source escrow released"
      # compensation: we paid on base but the source did not release in 30m.
      # Page a human - never auto-double-settle.
      - id: compensate
        if: "${{ steps.release_wait.output.timed_out is defined }}"
        notify:
          channel: ops
          message: "COMPENSATE order ${{ trigger.args.orderId }}: paid ${{ format_units(trigger.args.amount, 18) }} on base but source escrow did NOT release within 30m - investigate before any re-settle"
    on_failure: dead_letter

notifications:
  channels:
    ops:
      telegram:
        bot_token: ${TG_BOT_TOKEN}
        chat_id: ${TG_CHAT_ID}
```

### Required env vars

`DATABASE_URL`, `ETH_RPC`, `BASE_RPC`, `RAW_DANGEROUS_MNEMONIC`, `TG_BOT_TOKEN`,
`TG_CHAT_ID`.

### How the wait matches — read this

Inside a `wait_for:` event condition, **`trigger.*` is the *awaited* event**
(here `OrderSettled`), not the run's original `OrderOpened`. No other root
(`steps.*`, `constants.*`, …) is in scope at match time, so the `where:` can
only test the awaited event's own fields against literals. This recipe scopes
loosely (`amount > 0`) and leans on the timeout + the exactly-once `settle`
step. Two ways to key the wait to *this* order precisely:

* **Pin a literal** when the order id is known at deploy time:
  `where: "${{ trigger.args.orderId == '0x…' }}"`.
* **Cross-reference via `state:`** for fully dynamic matching — the
  [bridge message watcher](/use-cases/bridge-message-watch) pattern: a
  destination workflow `state_set`s a key per order id, and the waiting side
  gates on it. Use this when one settlement must resume exactly one run.

### Safety notes — money-moving

This workflow **pays a recipient on every fire**, so it carries the full
money-path guard set:

* **Reorg discipline** — the trigger fires only at `confirmations: 12` with
  `run_on: confirmed`, so a reorged `OrderOpened` never pays out; the awaited
  `OrderSettled` also settles at depth `12`.
* **Simulation** — `assert_sim: ["${{ sim.ok }}"]` pre-flight simulates the
  settlement before broadcast.
* **Gas caps** — `limit_from_simulation` + `max_price` abort on a gas spike.
* **Recheck** — `recheck:` drops the settlement if the order's own
  `fillDeadline` passed while the run got to broadcast.
* **Budget** — `settlement-hourly` caps cumulative destination payouts at
  `20 ether`/hour across every run (durable, race-safe). Add an
  [`approval:`](/approvals) gate on the `settle` step for large orders if a
  human should sign off.
* **Compensate, don't double-pay** — a timeout routes to a `compensate` step
  that **pages a human** rather than auto-retrying; `on_failure: dead_letter`
  journals anything that fails.

### Production checklist

1. replace the `Escrow` address and wire your real `OrderOpened` /
   `OrderSettled` events (`rflow abi fetch`)
2. decide the wait-matching strategy (literal pin vs `state:` cross-reference)
   for your escrow's event shape
3. replace the raw dev mnemonic with a production signer; fund the `settler`
   on the destination chain
4. rehearse the saga deterministically:
   `rflow test cross-chain-settlement --with-waits …` (see
   [backtesting](/backtesting))


## ERC-20 supply watch

**Template:** `community/erc20-supply-watch` · **category:** monitoring · **risk:** `monitor_only` · **community**

Watches an ERC-20 for large supply changes: a `Transfer` FROM the zero address
is a mint, TO the zero address is a burn. Each alert reads the resulting
`totalSupply()` so you see the new number in the same message. No signer, no
relayer, no transactions.

Community template: fetched SHA-pinned and hash-verified at install time. The
package ships NO ABI blob — the manifest declares the `token` interface
against the curated builtin `erc20` standard, and the install materializes
`abis/token.json` from it after verifying the declared `totalSupply()` and
`Transfer(address,address,uint256)` signatures.

### When to use it

* catch a surprise mint (inflation, a compromised minter role)
* watch a large burn (a buyback-and-burn, or a supply shock)
* keep an audit trail of a token's supply moves in a channel

### Generate it

```bash
# a full project (fetched from the registry, hash-verified, then gated)
rflow new --template community/erc20-supply-watch

# or add the workflow to an existing project
rflow add workflow community/erc20-supply-watch
```

Non-interactive (CI/agents):

```bash
rflow new --template community/erc20-supply-watch --yes --output ./supply \
  --answer token_address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  --answer min_amount=1000000
```

### Inputs

| key                                               | type                                    | default                                     |
| ------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                    | string                                  | `erc20-supply-watch`                        |
| `network` / `chain_id` / `rpc_env` / `rpc_url`    | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `token_name` / `token_address` / `token_decimals` | contract / address / int                | `Token` / USDC mainnet / `6`                |
| `min_amount`                                      | token\_amount                           | `1000000`                                   |
| `channel`                                         | string                                  | `ops`                                       |
| `tg_bot_token_env` / `tg_chat_id_env`             | env\_var                                | `TG_BOT_TOKEN` / `TG_CHAT_ID`               |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), and the telegram
credentials (default `TG_BOT_TOKEN` / `TG_CHAT_ID`) — all in the generated
`.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The install records the registry, commit and per-file sha256s in
`.rflow/template-lock.yaml`, and both workflows end in
`on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, set the token address + decimals
rflow validate
rflow start
```

### Common modifications

* drop `supply-burn` if you only care about mints
* tighten `min_amount` to catch smaller mints
* pair with the [large transfer alert](/use-cases/large-transfer-alert)


## ERC-4626 vault monitor

**Template:** `erc4626-vault-monitor` · **category:** monitoring · **risk:** `monitor_only`

Watches a tokenized vault (ERC-4626) three ways: large `Deposit`s, large
`Withdraw`s, and a share-price floor. The share-price workflow polls
`convertToAssets(1 share)` — the assets one share redeems for — and fires once
when it drops below your floor. A share price that only ever rises is the
whole ERC-4626 invariant; a drop is a loss event or an exploit.

### When to use it

* watch a yield vault for a share-price drop (bad debt, an exploit, a slashing)
* get paged on whale deposits/withdrawals that move the vault
* monitor a vault you allocate to without running its infra

### Generate it

```bash
rflow new --template erc4626-vault-monitor

# or add the workflow to an existing project
rflow add workflow erc4626-vault-monitor
```

Non-interactive (CI/agents):

```bash
rflow new --template erc4626-vault-monitor --yes --output ./vault \
  --answer min_deposit=100000 --answer min_share_price=0.98
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `erc4626-vault-monitor`                     |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `vault_name` / `vault_address`                 | contract / address                      | `Vault` / zero placeholder (replace!)       |
| `share_decimals` / `asset_decimals`            | int                                     | `18` / `6`                                  |
| `min_deposit`                                  | token\_amount                           | `100000`                                    |
| `min_share_price`                              | token\_amount                           | `0.98`                                      |
| `poll_every`                                   | duration                                | `1m`                                        |
| `channel`                                      | string                                  | `ops`                                       |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The share-price workflow is edge-triggered (one alert per de-peg, then
re-arms on recovery), and every workflow ends in `on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, set vault_address and the share/asset decimals
rflow validate
rflow start
```

### Common modifications

* tighten `min_share_price` for a hair-trigger de-peg alarm
* add a second `convertToAssets` poll at a large share count to watch rounding
* drop the deposit/withdraw workflows if you only care about the share price


## ERC-721 floor sweep watch

**Template:** `erc721-floor-sweep-watch` · **category:** monitoring · **risk:** `monitor_only`

Indexes an ERC-721 collection's `Transfer` events and pages when a single
wallet sweeps many of them in a short window — a floor buy-up, a bulk dump, or
a wash-trading burst. It uses a `query:` trigger over the indexed Transfer
table (no external cron/API), edge-triggered so one sweep is one alert.

### When to use it

* get paged when a whale sweeps the floor of a collection you track
* catch a bulk dump before the floor craters
* feed a trading or governance workflow off collection flow

### Generate it

```bash
rflow new --template erc721-floor-sweep-watch

# or add the workflow to an existing project
rflow add workflow erc721-floor-sweep-watch
```

Non-interactive (CI/agents):

```bash
rflow new --template erc721-floor-sweep-watch --yes --output ./sweep \
  --answer window="10 minutes" --answer sweep_threshold=5
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `erc721-floor-sweep-watch`                  |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `collection_name` / `collection_address`       | contract / address                      | `collection` / zero placeholder (replace!)  |
| `window`                                       | string (pg interval)                    | `10 minutes`                                |
| `sweep_threshold`                              | int                                     | `5`                                         |
| `poll_every`                                   | duration                                | `1m`                                        |
| `channel`                                      | string                                  | `ops`                                       |

`collection_name` is lowercase and drives the indexed table name
(`rflow_indexer_rflow_idx_<collection_name>.transfer`). Run `rflow tables` to
see the live table and drill into who swept.

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The contract is index-only (no event workflow triggers on it). The
query runs read-only, and the workflow ends in `on_failure: dead_letter`. Give
the indexer a moment to backfill the window before the first useful poll.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, set collection_address
rflow validate
rflow start
```

### Common modifications

* lower `sweep_threshold` / tighten `window` for a hair-trigger
* filter to mints (`"from"` = zero) by editing the query's `WHERE`
* widen the query to group by `"from"` to catch bulk dumps by seller


## ERC-7683 intent solver

**Template:** `erc7683-solver` · **category:** intents · **risk:** `money_moving`

An ERC-7683 `Open` event fires the solver pipeline: profitability quote in
the trigger, an on-chain race check, an inventory gate, an exact-amount
`approve`, then the simulated, gas-capped `fill`. Runnable sibling:
[`examples/erc7683-solver`](https://github.com/joshstevens19/rflow/tree/master/examples/erc7683-solver).

### When to use it

* run a filler against an ERC-7683-style settlement (`Open` event,
  `isFilled(bytes32)`, `fill(bytes32)`)
* as the skeleton for any "event → quote → race check → send" solver, even
  off-standard ones (adapt the signatures)

### Generate it

```bash
rflow new --template erc7683-solver
# or into an existing project (needs a signer; adds the `solver` relayer):
rflow add workflow erc7683-solver
```

### What the generated YAML does

1. **Trigger** — `Open` events on the settlement, quoted in `where:`: both
   token identities are pinned (`outputToken` must be the configured `Token`,
   `inputToken` must be that same token — comparing raw amounts of two
   different tokens is not a quote, and a hostile intent could otherwise
   trade worthless input for the solver's real inventory), then only intents
   whose escrowed `inputAmount` covers the requested `outputAmount` create a
   run (the spread is the solver's fee). The network's `confirmations: 12`
   means a reorged intent cannot orphan a paid fill.
2. **`unfilled`** — race check: asserts `isFilled(orderId) == false`
   (another solver may have won between the event and now).
3. **`inventory`** — asserts the solver wallet holds enough output tokens.
4. **`approve`** — allows the settlement to pull exactly this fill's output
   amount (gas-capped).
5. **`fill`** — delivers the output, collects the escrowed input: simulated
   first (a raced order **reverts in simulation** and nothing is
   broadcast), `assert_sim` checks `sim.ok` plus a `sim.gas_used` cap, a
   deadline `recheck` (`now() <= fillDeadline`) runs immediately before
   broadcast so an intent that expired during the approve wait is dropped,
   then held until `confirmed`.

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `erc7683-solver`                            |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `confirmations`                                | int                                     | `12`                                        |
| `settlement_address`                           | address                                 | zero placeholder — **replace it**           |
| `output_token_address`                         | address                                 | zero placeholder — **replace it**           |
| `gas_max_price`                                | string                                  | `50 gwei`                                   |
| `sim_gas_cap`                                  | int                                     | `500000`                                    |

### Required env vars

`DATABASE_URL`, the RPC env var, `RAW_DANGEROUS_MNEMONIC`. `rflow new` fills
`.env` with a freshly generated DEV-ONLY mnemonic — swap in a production
signer before real funds ride on this config.

### Safety defaults (all generated)

* quote in the trigger pins both token identities before comparing amounts —
  hostile and unprofitable intents never create a run
* race check + inventory gate (`read` + `assert`) before any send
* exact-amount `approve` (no unlimited allowances)
* pre-flight simulation + `assert_sim: ["${{ sim.ok }}", "${{ sim.gas_used < 500000 }}"]`
  — a raced order reverts in simulation and nothing is broadcast
* gas caps (`limit_from_simulation` + `max_price`) on approve AND fill
* `recheck` re-evaluates the fill deadline immediately before broadcast
* network `confirmations: 12`, `wait_for: confirmed`
* `concurrency.on_conflict: queue` — fills are serialized, never racing the
  same inventory
* `on_failure: dead_letter`

### Run it locally

```bash
docker compose up -d           # postgres on :5448
rflow validate                 # should be green out of the box
rflow test fill-intent --fixture fixtures/open-event.json  # dry-run rehearsal
rflow start                    # go live
```

The generated `fixtures/open-event.json` is a profitable same-token intent
(1050 in, 1000 out, both sides your configured output token) — flip the
amounts or swap in a foreign token address to rehearse the rejected paths
(no run is created).

### Production checklist

1. replace the `settlement_address` and `output_token_address` placeholders
2. replace the raw dev mnemonic with a production signer
3. fund the `solver` relayer with output-token inventory AND gas
4. tune the quote: the default `where:` ENFORCES same-token intents (both
   token identities pinned to your configured `Token`) because
   `outputAmount <= inputAmount` is only a quote within one token — to fill
   cross-token intents, replace the pins with a real pricing source (e.g. a
   `command:` quote step), never with a bare amount comparison
5. add a notification channel on the dead-letter path; a stream of raced
   fills means your latency budget needs work

### Common modifications

* **Cross-chain fills**: add the destination network, list it on the
  `solver` relayer (one wallet, cloned onto both chains) and point the
  `fill` step's `network:` at it — see the commented variant in
  `examples/erc7683-solver`.
* **Minimum spread**: tighten the trigger to
  `outputAmount * 10050 <= inputAmount * 10000` for a 0.5% floor.
* **Deadline guard**: the fill's `recheck` already drops a send whose
  `fillDeadline` expired pre-broadcast; add `and now() <= trigger.args.fillDeadline`
  to the trigger `where:` so expired intents never even create a run.
* **Standing allowance**: replace the per-fill `approve` with a one-time
  manual allowance and delete the step (cheaper, less strict).


## Hot wallet refill

**Recipe** (no bundled template) · **category:** treasury · **risk:** `money_moving`

Keep a hot wallet topped up automatically: a `read` trigger polls the wallet's
native balance every minute and, on the false→true crossing under a floor,
tops it back up to a target from a funding wallet — pre-flight simulated,
gas-capped, dropped if stale, and behind a durable daily
[budget](/workflows/budgets) so a bad trigger can never drain the funder.

Closest bundled starting points: the
[relayer low-balance alert](/use-cases/relayer-low-balance-alert) template
(the same `Multicall3.getEthBalance` read, alert-only) and the
[treasury sweep](/use-cases/treasury-sweep-approval) template (the
simulate + gas-cap + confirm money path). This page is the money-moving
combination of the two.

### When to use it

* keep a keeper/relayer/paymaster wallet funded without a human topping it up
* refill a gas tank when it dips below a floor, up to a target
* any "watch a native balance, send when it crosses a threshold" auto-funder

### The config

The `read` trigger fires on the crossing under the floor; a `command:` step
plans the exact top-up and stamps a freshness deadline; the send is native,
simulated, gas-capped, `recheck`-guarded and budget-capped.

```yaml
# recipe: full
rflow_version: 1
name: hot-wallet-refill

config:
  port: 3947
  db_connection: ${DATABASE_URL}

networks:
  - name: ethereum
    chain_id: 1
    rpc: ${ETH_RPC}
    # a refill only counts once it is 6 blocks deep
    confirmations: 6

# DEV ONLY raw mnemonic (from .env) - `rflow new` generates a fresh dev seed.
# Swap in a production signer before real funds ride on this config.
signer:
  raw:
    mnemonic: ${RAW_DANGEROUS_MNEMONIC}

relayers:
  # the funding wallet - ITS native balance tops up the hot wallet
  funder:
    networks: [ethereum]
    speed: FAST
    # belt-and-braces: this relayer may only ever pay the hot wallet
    policy:
      max_gas_price: "80 gwei"
      whitelist_receivers:
        - "0x000000000000000000000000000000000000dEaD"

contracts:
  # Multicall3 is deployed at the same address on 250+ chains; its
  # getEthBalance(address) view is the cheapest native-balance read
  Multicall3:
    abi: ./abis/multicall3.json
    addresses:
      ethereum: "0xcA11bde05977b3631167028862bE2a173976CA11"

constants:
  # the hot wallet to keep funded - replace the placeholder (and the
  # whitelist_receivers entry above with the same address)
  hot_wallet: "0x000000000000000000000000000000000000dEaD"

budgets:
  # blast-radius cap: at most 5 ETH of refills in any 24h window, no matter
  # how often the balance dips - a bad trigger cannot drain the funder
  refill-daily:
    window: 24h
    max_native_value: "5 ether"
    scope:
      relayers: [funder]
      networks: [ethereum]

workflows:
  hot-wallet-refill:
    trigger:
      # edge-triggered: ONE refill on the false->true crossing under 0.5 ETH,
      # not one per poll while the balance sits low
      read:
        contract: Multicall3
        network: ethereum
        function: "getEthBalance(address)"
        args: ["${{ constants.hot_wallet }}"]
        every: 1m
        condition: "${{ output < wei('0.5', 18) }}"
        mode: threshold
    # one refill in flight at a time - later dips are skipped, not stacked
    concurrency:
      group: "hot-wallet-refill"
      on_conflict: skip
    # every send in this workflow charges the daily cap
    budgets: [refill-daily]
    steps:
      # your script tops the wallet back up TO a target and stamps a short
      # freshness deadline: { "top_up_wei": "...", "valid_until": "<iso>" }
      - id: plan
        command:
          run: "node ./scripts/plan-refill.js"
          timeout: 10s
          output: json
          input:
            balance_wei: "${{ trigger.args.output }}"
            target_eth: "1"
            now: "${{ now() }}"
      # the funder must be able to cover the top-up (plus its own gas)
      - id: funder_balance
        read:
          contract: Multicall3
          network: ethereum
          function: "getEthBalance(address)"
          args: ["${{ relayers.funder.address }}"]
          assert: "${{ output >= steps.plan.output.top_up_wei }}"
      # the money step: native transfer, pre-flight simulated, gas-capped,
      # dropped if the plan went stale, then confirmed
      - id: refill
        send_transaction:
          network: ethereum
          relayer: funder
          to: "${{ constants.hot_wallet }}"
          value: "${{ steps.plan.output.top_up_wei }}"
          assert_sim:
            - "${{ sim.ok }}"
          gas:
            limit_from_simulation: true
            multiplier: 1.2
            max_price: "80 gwei"
          # don't fire a refill the plan stamped more than ~2m ago
          recheck: "${{ now() < steps.plan.output.valid_until }}"
          wait_for: confirmed
    on_failure: dead_letter
```

### The `plan-refill.js` command

The `plan` step shells out to your script (stdin = the `input:` map as JSON,
stdout = one JSON object). A minimal implementation:

```js
// scripts/plan-refill.js
const chunks = [];
process.stdin.on('data', (c) => chunks.push(c));
process.stdin.on('end', () => {
  const { balance_wei, target_eth, now } = JSON.parse(chunks.join(''));
  const target = BigInt(target_eth) * 10n ** 18n;
  const top_up = target - BigInt(balance_wei);
  process.stdout.write(
    JSON.stringify({
      top_up_wei: top_up > 0n ? top_up.toString() : '0',
      // short freshness window: the refill is dropped if it hasn't broadcast
      // within ~2 minutes (queue delay, retries, restarts). Unix seconds, so
      // `now() < valid_until` compares like-for-like in the recheck.
      valid_until: Number(now) + 120,
    }),
  );
});
```

### Required env vars

`DATABASE_URL`, `ETH_RPC`, `RAW_DANGEROUS_MNEMONIC`. Generate a dev signer with
`rflow new` and swap in a production signer before real funds ride on this
config.

### Safety notes — money-moving

This workflow **moves native value on every fire**, so it carries the full
money-path guard set:

* **Simulation** — `assert_sim: ["${{ sim.ok }}"]` pre-flight simulates the
  transfer; a send the funder cannot cover reverts in `eth_call` and
  dead-letters instead of broadcasting.
* **Gas caps** — `limit_from_simulation` + `max_price` (and the relayer
  `policy.max_gas_price`) abort the send before queueing if gas spikes.
* **Recheck** — `recheck:` re-evaluates immediately before broadcast, so a
  refill the `plan` stamped more than \~2m ago (queue delay, retries, a
  restart) is dropped rather than fired stale.
* **Budget (not approval)** — an unattended refiller should not gate on a
  human, so the blast-radius cap here is a durable
  [budget](/workflows/budgets): `refill-daily` caps cumulative refills at
  `5 ether` per 24h across every run, and reservations survive restarts and
  races. Add [`permissions.max_value_per_tx`](/workflows/budgets#how-budgets-compose)
  for a per-send ceiling too, and an [`approval:`](/approvals) gate if you
  want a human on refills above some size.
* **Receiver allow-list** — `policy.whitelist_receivers` pins the only
  address the funder may ever pay.
* **Reorg-safe** — `confirmations: 6` + `wait_for: confirmed`; `on_failure:
  dead_letter` journals a failed refill instead of losing it.

### Production checklist

1. replace the `hot_wallet` constant **and** the matching
   `whitelist_receivers` entry with the real address
2. replace the raw dev mnemonic with a production signer, and fund the
   `funder` wallet
3. tune the floor (`0.5 ETH`), the target (`target_eth`) and the
   `refill-daily` cap to your burn rate
4. dry-run first: `rflow test hot-wallet-refill --fixture <low-balance read>`


## Cookbook

Copyable recipes for real onchain jobs. Each page says **what it does**, **when
to use it**, the **YAML**, the **env vars/secrets** it needs, a **risk label**,
and **safety notes** — and links to a runnable template or example where one
exists.

Most recipes are backed by a bundled **template**: scaffold a whole project
with `rflow new --template <id>` or drop the workflow into an existing project
with `rflow add workflow <id>` (see the [templates guide](/templates)). Three
recipes have **no template** — they inline a complete, validated `rflow.yaml`
you copy directly:
[hot wallet refill](/use-cases/hot-wallet-refill),
[stablecoin pause / blacklist monitor](/use-cases/stablecoin-pause-monitor) and
[cross-chain settlement saga](/use-cases/cross-chain-settlement-saga).

### Risk labels

Every recipe carries one, so you know what it can do before you run it:

| Label          | Meaning                                                                                                                                                                                                                                                                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `monitor_only` | Reads and notifies. No `signer:`, no `relayers:` — the relayer engine never boots and it cannot move funds.                                                                                                                                                                                                                                                           |
| `prepares_tx`  | Validates/decides/dedupes and prepares a transaction, but never signs or sends.                                                                                                                                                                                                                                                                                       |
| `money_moving` | Signs and broadcasts transactions. Every one shows [simulation](/workflows/steps/send-transaction#simulation-is-the-default), [gas caps](/workflows/steps/send-transaction#gas--client-side-guardrails), a [`recheck`](/workflows/steps/send-transaction#recheck--dont-fire-stale) and an [approval](/approvals) **or** [budget](/workflows/budgets) — no exceptions. |

### Use-case matrix

Find the closest recipe fast: match your job → risk → trigger → the recipe.

| Use case                                                                    | Risk           | Trigger           | Scaffold / runnable                                                                                                                      |
| --------------------------------------------------------------------------- | -------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| [Large transfer alert](/use-cases/large-transfer-alert)                     | `monitor_only` | event             | `rflow new --template large-transfer-alert`                                                                                              |
| [Large approval alert](/use-cases/large-approval-alert)                     | `monitor_only` | event             | `rflow new --template community/large-approval-alert` (community)                                                                        |
| [Chainlink oracle staleness](/use-cases/chainlink-oracle-staleness)         | `monitor_only` | read (poll)       | `rflow new --template chainlink-oracle-staleness`                                                                                        |
| [Workflow error pager](/use-cases/workflow-error-pager)                     | `monitor_only` | workflow\_error   | `rflow new --template workflow-error-pager`                                                                                              |
| [Relayer low-balance alert](/use-cases/relayer-low-balance-alert)           | `monitor_only` | read (poll)       | `rflow new --template relayer-low-balance-alert`                                                                                         |
| [Bridge message watch](/use-cases/bridge-message-watch)                     | `monitor_only` | event             | `rflow new --template bridge-message-watch`                                                                                              |
| [Price alert stream](/use-cases/price-alert-stream)                         | `monitor_only` | stream (WS)       | `rflow new --template price-alert-stream`                                                                                                |
| [Security advisory watch](/use-cases/security-advisory-watch)               | `monitor_only` | web (HTTP poll)   | `rflow new --template security-advisory-watch`                                                                                           |
| [Chainlink deviation alert](/use-cases/chainlink-deviation-alert)           | `monitor_only` | cron              | `rflow new --template chainlink-deviation-alert`                                                                                         |
| [ERC-4626 vault monitor](/use-cases/erc4626-vault-monitor)                  | `monitor_only` | event + read      | `rflow new --template erc4626-vault-monitor`                                                                                             |
| [Uniswap v3 LP monitor](/use-cases/uniswap-v3-lp-monitor)                   | `monitor_only` | event + read      | `rflow new --template uniswap-v3-lp-monitor`                                                                                             |
| [ERC-721 floor sweep watch](/use-cases/erc721-floor-sweep-watch)            | `monitor_only` | query (poll)      | `rflow new --template erc721-floor-sweep-watch`                                                                                          |
| [Solver PnL report](/use-cases/solver-pnl-report)                           | `monitor_only` | cron              | `rflow new --template solver-pnl-report`                                                                                                 |
| [Uniswap v2 price alert](/use-cases/uniswap-v2-price-alert)                 | `monitor_only` | event             | `rflow new --template community/uniswap-v2-price-alert` (community)                                                                      |
| [ERC-20 supply watch](/use-cases/erc20-supply-watch)                        | `monitor_only` | event             | `rflow new --template community/erc20-supply-watch` (community)                                                                          |
| [WETH wrap monitor](/use-cases/weth-wrap-monitor)                           | `monitor_only` | event             | `rflow new --template community/weth-wrap-monitor` (community)                                                                           |
| [Safe multisig monitor](/use-cases/safe-monitor)                            | `monitor_only` | event             | `rflow new --template safe-monitor`                                                                                                      |
| [Safe owner change alert](/use-cases/safe-owner-change-alert)               | `monitor_only` | event             | `rflow new --template safe-owner-change-alert`                                                                                           |
| [Proxy upgrade alert](/use-cases/proxy-upgrade-alert)                       | `monitor_only` | event             | `rflow new --template proxy-upgrade-alert`                                                                                               |
| [Timelock monitor](/use-cases/timelock-monitor)                             | `monitor_only` | event             | `rflow new --template timelock-monitor`                                                                                                  |
| [Stablecoin pause / blacklist monitor](/use-cases/stablecoin-pause-monitor) | `monitor_only` | event + read      | copy recipe (no template)                                                                                                                |
| [Cron HTTP report](/use-cases/cron-http-report)                             | `monitor_only` | cron              | `rflow new --template cron-http-report`                                                                                                  |
| [Native spend report](/use-cases/native-spend-report)                       | `monitor_only` | cron              | `rflow new --template native-spend-report`                                                                                               |
| [Command decision](/use-cases/command-decision)                             | `monitor_only` | cron              | `rflow new --template command-decision` · [example](https://github.com/joshstevens19/rflow/tree/master/examples/command-decision)        |
| [Webhook idempotent handler](/use-cases/webhook-idempotent-handler)         | `prepares_tx`  | webhook           | `rflow new --template webhook-idempotent-handler`                                                                                        |
| [Treasury sweep with approval](/use-cases/treasury-sweep-approval)          | `money_moving` | cron              | `rflow new --template treasury-sweep-approval` · [example](https://github.com/joshstevens19/rflow/tree/master/examples/treasury-ops)     |
| [Hot wallet refill](/use-cases/hot-wallet-refill)                           | `money_moving` | read (poll)       | copy recipe (no template)                                                                                                                |
| [Token deposit relay](/use-cases/token-deposit-relay)                       | `money_moving` | event             | `rflow new --template token-deposit-relay` · [example](https://github.com/joshstevens19/rflow/tree/master/examples/token-transfer-relay) |
| [Liquidation keeper](/use-cases/liquidation-keeper)                         | `money_moving` | read (poll)       | `rflow new --template liquidation-keeper` · [example](https://github.com/joshstevens19/rflow/tree/master/examples/liquidation-keeper)    |
| [Aave v3 health guardian](/use-cases/aave-health-guardian)                  | `money_moving` | read (poll)       | `rflow new --template aave-health-guardian`                                                                                              |
| [Solver inventory rebalance](/use-cases/solver-inventory-rebalance)         | `money_moving` | read (poll)       | `rflow new --template solver-inventory-rebalance`                                                                                        |
| [ERC-7683 intent solver](/use-cases/erc7683-solver)                         | `money_moving` | event             | `rflow new --template erc7683-solver` · [example](https://github.com/joshstevens19/rflow/tree/master/examples/erc7683-solver)            |
| [Cross-chain settlement saga](/use-cases/cross-chain-settlement-saga)       | `money_moving` | event + wait\_for | copy recipe (no template)                                                                                                                |
| [Command trade prep](/use-cases/command-trade-prep)                         | `money_moving` | event             | `rflow new --template command-trade-prep` · [example](https://github.com/joshstevens19/rflow/tree/master/examples/command-trade-prep)    |

### By category

#### Security & governance

* [Safe multisig monitor](/use-cases/safe-monitor) — `safe-monitor` · `monitor_only`
* [Proxy upgrade alert](/use-cases/proxy-upgrade-alert) — `proxy-upgrade-alert` · `monitor_only`
* [Timelock monitor](/use-cases/timelock-monitor) — `timelock-monitor` · `monitor_only`
* [Stablecoin pause / blacklist monitor](/use-cases/stablecoin-pause-monitor) — recipe · `monitor_only`
* [Safe owner change alert](/use-cases/safe-owner-change-alert) — `safe-owner-change-alert` · `monitor_only`
* [Security advisory watch](/use-cases/security-advisory-watch) — `security-advisory-watch` · `monitor_only`
* [Large approval alert](/use-cases/large-approval-alert) — `community/large-approval-alert` · `monitor_only` · community

#### Monitoring & alerting

* [Large transfer alert](/use-cases/large-transfer-alert) — `large-transfer-alert` · `monitor_only`
* [Chainlink oracle staleness](/use-cases/chainlink-oracle-staleness) — `chainlink-oracle-staleness` · `monitor_only`
* [Chainlink deviation alert](/use-cases/chainlink-deviation-alert) — `chainlink-deviation-alert` · `monitor_only`
* [Workflow error pager](/use-cases/workflow-error-pager) — `workflow-error-pager` · `monitor_only`
* [Relayer low balance alert](/use-cases/relayer-low-balance-alert) — `relayer-low-balance-alert` · `monitor_only`
* [Bridge message watch](/use-cases/bridge-message-watch) — `bridge-message-watch` · `monitor_only`
* [Price alert stream](/use-cases/price-alert-stream) — `price-alert-stream` · `monitor_only`
* [ERC-4626 vault monitor](/use-cases/erc4626-vault-monitor) — `erc4626-vault-monitor` · `monitor_only`
* [Uniswap v3 LP monitor](/use-cases/uniswap-v3-lp-monitor) — `uniswap-v3-lp-monitor` · `monitor_only`
* [ERC-721 floor sweep watch](/use-cases/erc721-floor-sweep-watch) — `erc721-floor-sweep-watch` · `monitor_only`
* [Uniswap v2 price alert](/use-cases/uniswap-v2-price-alert) — `community/uniswap-v2-price-alert` · `monitor_only` · community
* [ERC-20 supply watch](/use-cases/erc20-supply-watch) — `community/erc20-supply-watch` · `monitor_only` · community
* [WETH wrap monitor](/use-cases/weth-wrap-monitor) — `community/weth-wrap-monitor` · `monitor_only` · community

#### Treasury

* [Treasury sweep with approval](/use-cases/treasury-sweep-approval) — `treasury-sweep-approval` · `money_moving`
* [Hot wallet refill](/use-cases/hot-wallet-refill) — recipe · `money_moving`
* [Native spend report](/use-cases/native-spend-report) — `native-spend-report` · `monitor_only`

#### Relaying, keepers & intents

* [Token deposit relay](/use-cases/token-deposit-relay) — `token-deposit-relay` · `money_moving`
* [Liquidation keeper](/use-cases/liquidation-keeper) — `liquidation-keeper` · `money_moving`
* [Aave v3 health guardian](/use-cases/aave-health-guardian) — `aave-health-guardian` · `money_moving`
* [ERC-7683 intent solver](/use-cases/erc7683-solver) — `erc7683-solver` · `money_moving`
* [Solver inventory rebalance](/use-cases/solver-inventory-rebalance) — `solver-inventory-rebalance` · `money_moving`
* [Solver PnL report](/use-cases/solver-pnl-report) — `solver-pnl-report` · `monitor_only`
* [Cross-chain settlement saga](/use-cases/cross-chain-settlement-saga) — recipe · `money_moving`
* [Command trade prep](/use-cases/command-trade-prep) — `command-trade-prep` · `money_moving`

#### Off-chain & custom logic

* [Cron HTTP report](/use-cases/cron-http-report) — `cron-http-report` · `monitor_only`
* [Webhook idempotent handler](/use-cases/webhook-idempotent-handler) — `webhook-idempotent-handler` · `prepares_tx`
* [Command decision](/use-cases/command-decision) — `command-decision` · `monitor_only`

### Every full recipe validates

The cookbook's full configs are not decoration — they are checked in CI.
`documentation/scripts/check-recipes.mjs` extracts every complete `rflow.yaml`
from these pages and runs the real `rflow validate` over each in a throwaway
project (ABIs stubbed, env vars stubbed). Yaml blocks are classified by a
first-line marker:

* `# recipe: full` — a complete `rflow.yaml`; the validator asserts it passes.
* `# recipe: partial` — a fragment (one trigger/step/section) shown for
  teaching; skipped.

An unmarked yaml block in a cookbook page fails the check, so nothing escapes
classification. Run it locally with `node scripts/check-recipes.mjs` from
`documentation/` (it builds `rflow` if needed).


## Large approval alert

**Template:** `community/large-approval-alert` · **category:** security · **risk:** `monitor_only` · **community**

Watches `Approval` events on an ERC20 token and notifies a telegram channel
when an approval crosses a threshold — an outsized approval is the classic
prelude to a drain. No signer, no relayer, no transactions.

This is the seed COMMUNITY template: it lives under `templates/community/`
in the rflow repo (not in the binary) and is fetched SHA-pinned and
hash-verified at install time. The install prints a provenance banner
(registry, commit, risk) and runs the full community gate before anything
renders.

### When to use it

* watch a treasury or hot wallet for approvals it should never grant
* catch a phishing-signed `approve` before the drain transaction lands
* as a template for your own first community submission (see
  `templates/community/SUBMITTING.md` in the repo)

### Generate it

```bash
# a full project (fetched from the registry, hash-verified, then gated)
rflow new --template community/large-approval-alert

# or add the workflow to an existing project
rflow add workflow community/large-approval-alert

# browse the community index first
rflow templates ls --community
```

Non-interactive (CI/agents):

```bash
rflow new --template community/large-approval-alert --yes --output ./approvals \
  --answer network=ethereum --answer min_amount=500000
```

### Inputs

| key                                               | type                                    | default                                     |
| ------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                    | string                                  | `large-approval-alert`                      |
| `network` / `chain_id` / `rpc_env` / `rpc_url`    | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `token_name` / `token_address` / `token_decimals` | contract / address / int                | `USDC` mainnet                              |
| `min_amount`                                      | token\_amount                           | `1000000`                                   |
| `channel`                                         | string                                  | `ops`                                       |
| `tg_bot_token_env` / `tg_chat_id_env`             | env\_var                                | `TG_BOT_TOKEN` / `TG_CHAT_ID`               |

### The declared interface

The package ships NO ABI blob. Its manifest declares the surface it uses:

```yaml
# recipe: partial
interfaces:
  token:
    abi:
      wellknown: erc20
    events:
      - "Approval(address,address,uint256)"
```

The install materializes `abis/token.json` from the curated builtin ERC20
standard and verifies the declared `Approval` topic0 against it — a reviewer
reads one signature; the machine proves the bytes match.

### The generated workflow

```yaml
# recipe: partial
workflows:
  large-approval-alert:
    trigger:
      event:
        contract: USDC
        name: Approval
        network: ethereum
        where: "${{ trigger.args.value > wei('1000000', 6) }}"
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: alert
        notify:
          channel: ops
          message: "large approval: ${{ trigger.args.owner }} approved ${{ format_units(trigger.args.value, 6) }} USDC to ${{ trigger.args.spender }} in ${{ trigger.tx_hash }}"
    on_failure: dead_letter
```

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), and the telegram
credentials (default `TG_BOT_TOKEN` / `TG_CHAT_ID`) — all listed in the
generated `.env.example`.

### Safety notes

Monitor-only: the generated config declares no `signer:` and no `relayers:`,
so the relayer engine never boots. The install records the registry, commit
and per-file sha256s in `.rflow/template-lock.yaml`, and the workflow ends in
`on_failure: dead_letter` so a failed notification is journaled, never lost.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + telegram credentials)
rflow validate
rflow start
```

### Common modifications

* raise `confirmations:` on the trigger to trade latency for reorg safety
* filter to approvals FROM your own wallets with a tighter `where:` clause
* swap the channel for slack/discord/pagerduty: `rflow add notification`
* pair it with the [large transfer alert](/use-cases/large-transfer-alert)
  on the same token


## Large transfer alert

**Template:** `large-transfer-alert` · **category:** monitoring · **risk:** `monitor_only`

Watches `Transfer` events on an ERC20 token and notifies a telegram channel
when a transfer crosses a threshold. No signer, no relayer, no transactions —
the safest possible starting project.

### When to use it

* watch a treasury, bridge, or whale wallet for big token moves
* get paged before your own dashboards notice
* as the first monitoring workflow in a fresh rflow project

### Generate it

```bash
# a full project
rflow new --template large-transfer-alert

# or add the workflow to an existing project (asks only for missing inputs)
rflow add workflow large-transfer-alert
```

Non-interactive (CI/agents):

```bash
rflow new --template large-transfer-alert --yes --output ./alerts \
  --answer network=ethereum --answer min_amount=250000
```

### Inputs

| key                                               | type                                    | default                                     |
| ------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                    | string                                  | `large-transfer-alert`                      |
| `network` / `chain_id` / `rpc_env` / `rpc_url`    | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `token_name` / `token_address` / `token_decimals` | contract / address / int                | `USDC` mainnet                              |
| `min_amount`                                      | token\_amount                           | `100000`                                    |
| `channel`                                         | string                                  | `ops`                                       |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: the generated config declares no `signer:` and no `relayers:`,
so the relayer engine never boots. The workflow ends in
`on_failure: dead_letter` so a failed notification is journaled, never lost.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + telegram credentials)
rflow validate
rflow start
```

### Common modifications

* raise `confirmations:` on the trigger to trade latency for reorg safety
* swap the channel for slack/discord/pagerduty: `rflow add notification`
* alert into a runtime watchlist instead: see [state and lists](/workflows/steps/state-and-lists)


## Liquidation keeper

**Template:** `liquidation-keeper` · **category:** keeper · **risk:** `money_moving`

A `read` trigger polls `healthFactor(borrower)` on a lending pool; when it
crosses below the threshold the keeper re-reads the position and fires a
simulated, gas-capped `liquidate(address)`. Runnable sibling:
[`examples/liquidation-keeper`](https://github.com/joshstevens19/rflow/tree/master/examples/liquidation-keeper).

### When to use it

* run a liquidation bot against Aave-style pools with `healthFactor`-shaped
  views
* any "poll a view function, send when a threshold crosses" keeper (adapt
  the function and condition)

### Generate it

```bash
rflow new --template liquidation-keeper
# or into an existing project (needs a signer; adds the `keeper` relayer):
rflow add workflow liquidation-keeper
```

### What the generated YAML does

1. **Trigger** — polls `healthFactor(borrower)` every `poll_every`
   (default 15s) and fires on the false→true **crossing** of
   `output < wei(min_health, 18)` (`mode: threshold` is edge-triggered — a
   position sitting underwater does not re-fire every poll).
2. **`health`** — a fresh read right before the money step; a position
   repaid between the poll and now makes the run succeed quietly.
3. **`liquidate`** — gated by `if:` on the fresh read, simulated as the
   keeper (a healthy position **reverts in simulation** and nothing is
   broadcast), `assert_sim` checks `sim.ok` and a `sim.gas_used` cap, and
   the gas policy caps price and limit. The simulation is also the
   healed-position guard at broadcast time — a position repaid after the
   `health` read reverts in `eth_call` and dead-letters instead of
   broadcasting.

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `liquidation-keeper`                        |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `confirmations`                                | int                                     | `3`                                         |
| `pool_address`                                 | address                                 | zero placeholder — **replace it**           |
| `borrower`                                     | address                                 | zero placeholder — **replace it**           |
| `poll_every`                                   | duration                                | `15s`                                       |
| `min_health` / `health_decimals`               | token\_amount / int                     | `1` / `18`                                  |
| `gas_max_price`                                | string                                  | `50 gwei`                                   |
| `sim_gas_cap`                                  | int                                     | `300000`                                    |

### Required env vars

`DATABASE_URL`, the RPC env var, `RAW_DANGEROUS_MNEMONIC`. `rflow new` fills
`.env` with a freshly generated DEV-ONLY mnemonic — swap in a production
signer before real funds ride on this config.

### Safety defaults (all generated)

* edge-triggered poll (`mode: threshold`) — one run per crossing
* fresh read + `if:` gate before the send
* pre-flight simulation + `assert_sim: ["${{ sim.ok }}", "${{ sim.gas_used < 300000 }}"]`
  — this is the healed-position guard: liquidating a healthy position
  reverts in simulation instead of broadcasting (a `recheck` would only
  re-test the journaled health read the `if:` gate already passed, so the
  template ships none)
* gas cap: `limit_from_simulation`, `multiplier: 1.3`, `max_price`
* `concurrency.on_conflict: skip` — one liquidation in flight at a time
* `wait_for: confirmed`, `on_failure: dead_letter`

### Run it locally

```bash
docker compose up -d           # postgres on :5448
rflow validate                 # should be green out of the box
rflow test liquidation-keeper --fixture fixtures/underwater-read.json  # dry-run rehearsal
rflow start                    # go live
```

The generated `fixtures/underwater-read.json` is a `0.9` health factor —
`rflow test` dry-runs the whole pipeline (including the simulated send)
without broadcasting.

### Production checklist

1. replace the `pool_address` and `borrower` placeholders
2. replace the raw dev mnemonic with a production signer
3. fund the `keeper` relayer with gas; verify the liquidation bonus covers
   your `gas_max_price` worst case
4. tighten `poll_every` to your latency budget (every poll is an RPC call)
5. add a notification channel on the dead-letter path so failed
   liquidations page someone
6. cap the blast radius of a bad deploy or oracle glitch with a durable
   [budget](/workflows/budgets) on the `liquidate` step (e.g. a max number
   of liquidations / total gas per hour), and add an [`approval:`](/approvals)
   gate if a human should sign off before the first live liquidation

### Common modifications

* **Many borrowers**: move `borrower` into a `list:` seeded by an event
  workflow, and `foreach` over it.
* **Profit guard**: read the collateral price first and add an `if:`
  comparing expected bonus to `sim.gas_used * gas price`.
* **Partial liquidations**: swap `liquidate(address)` for your pool's
  `liquidationCall(...)` signature with an amount argument.
* **Faster sends**: set the relayer `speed: FAST` (see
  `examples/liquidation-keeper`).


## Native spend report

**Template:** `native-spend-report` · **category:** treasury · **risk:** `monitor_only`

A scheduled treasury report over rflow's **own journal**: every
`send_transaction` step journals the tx it queued — including the native
value it attached — so one cron plus one read-only
[`query:` step](/workflows/steps/query) aggregates the send history of the
last N hours into an HMAC-signed HTTP report and a chat summary. It reads
the journal; it never sends.

### When to use it

* a daily "what did our automation actually spend" digest for the treasury
  channel
* feed a finance/ops dashboard from the same journal your workflows already
  write — no extra indexing
* an independent sanity check on money-moving workflows: sends and totals,
  counted from the journal, not from the workflow's own logs

### Generate it

```bash
# usually: add the report to the project that actually sends
rflow add workflow native-spend-report

# or standalone, pointed (via DATABASE_URL) at a sending project's journal
rflow new --template native-spend-report
```

Non-interactive (CI/agents):

```bash
rflow new --template native-spend-report --yes --output ./spend-report \
  --answer report_cron="0 8 * * *" --answer report_window="24 hours"
```

### The generated YAML

```yaml
# recipe: partial
workflows:
  native-spend-report:
    trigger:
      cron:
        expression: "0 8 * * *"
    steps:
      - id: spend
        query:
          sql: >-
            WITH sends AS (
              SELECT wr.workflow_name,
                     COALESCE((sr.output->>'value')::numeric, 0) AS value_wei
              FROM rflow.step_runs sr
              JOIN rflow.workflow_runs wr ON wr.id = sr.run_id
              WHERE sr.tx_hash IS NOT NULL
                AND sr.status = 'succeeded'
                AND sr.finished_at >= now() - interval '24 hours'
            )
            SELECT COUNT(*) AS sends,
                   COUNT(DISTINCT workflow_name) AS workflows,
                   COALESCE(SUM(value_wei), 0) AS native_wei_out
            FROM sends
      - id: report
        http_call:
          url: https://ops.example.com/native-spend
          hmac: "${{ secrets.report_hmac }}"
          body:
            report: native-spend
            sends: "${{ steps.spend.output.sends }}"
            native_out: "${{ format_units(steps.spend.output.native_wei_out, 18) }} ETH"
      - id: summary
        notify:
          channel: ops
          message: "native spend, last 24 hours: ${{ format_units(steps.spend.output.native_wei_out, 18) }} ETH across ${{ steps.spend.output.sends }} send(s) from ${{ steps.spend.output.workflows }} workflow(s)"
    on_failure: dead_letter
```

### Inputs

| key             | type                              | default                                |
| --------------- | --------------------------------- | -------------------------------------- |
| `project_name`  | string                            | `native-spend-report`                  |
| `report_cron`   | cron                              | `0 8 * * *` (daily, 08:00)             |
| `report_window` | string (`N minutes\|hours\|days`) | `24 hours`                             |
| `report_url`    | string                            | `https://ops.example.com/native-spend` |
| `hmac_env`      | env\_var                          | `REPORT_HMAC_SECRET`                   |
| `native_symbol` | string                            | `ETH`                                  |
| `channel`       | string                            | `ops`                                  |

### Required env vars

`DATABASE_URL`, the HMAC secret env var (default `REPORT_HMAC_SECRET`),
`TG_BOT_TOKEN`, `TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

* Monitor-only: no networks, no signer — neither embedded engine boots.
* The SQL is a single read-only statement executed inside a Postgres
  `READ ONLY` transaction; `${{ }}` inside `sql:` is a hard validation error
  by design (the window is baked in at scaffold time).
* Numbers stay **exact**: `value` aggregates as Postgres `NUMERIC` and
  crosses into expressions as an exact integer, so `format_units` never sees
  a float.
* Sends journaled by rflow builds that predate value journaling have no
  `value` on their output and count as 0.
* The report body is HMAC-SHA256-signed with `report_hmac`, so the receiver
  can verify it — `fixtures/report-body.json` shows the exact shape.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (HMAC secret + telegram credentials)
rflow validate
rflow start
```

An empty journal reports zeros (the aggregate always returns one row). To see
real numbers, add it to a project that sends — the query counts journaled
`send_transaction` steps with a tx hash — and set `report_cron` to something
fast (e.g. `*/2 * * * *`) while testing.

### Production checklist

* [ ] the report reads the SAME database the sending project writes: add the
  workflow to that project, or share its `DATABASE_URL`
* [ ] the receiving endpoint verifies the HMAC (same secret, SHA-256 over the
  body)
* [ ] `report_window` matches the cron cadence (daily cron ⇒ `24 hours`), or
  windows will overlap/gap
* [ ] mind [retention/pruning](/self-hosting): the window must be shorter
  than how long journal rows are kept
* [ ] a missed schedule slot is skipped by default — set
  `cron.catch_up: true` if a late report is better than none
* [ ] pair with [`workflow-error-pager`](/use-cases/workflow-error-pager) so
  a failing report run pages someone

### Common modifications

* per-workflow breakdown: `SELECT workflow_name, COUNT(*),
  SUM(value_wei) ... GROUP BY workflow_name` — N rows come through as an
  array of objects
* track ERC20 spend instead: aggregate the indexed `transfer` tables
  (`rflow_indexer_rflow_idx_<token>.transfer`) — see the
  [query docs](/workflows/steps/query#where-the-data-lives--the-table-naming-rule)
* alert instead of report: put the same SQL on a
  [query **trigger**](/workflows/triggers/query) with `condition: "${{ output >
  wei('10', 18) }}"` to page when spend crosses a budget
* drop the `http_call:` (chat only) or the `notify:` (dashboard only)


## Price alert stream

**Template:** `price-alert-stream` · **category:** monitoring · **risk:** `monitor_only`

Subscribe to a public price WebSocket feed, filter by symbol and a price
threshold, and notify a channel — as an ordinary, durable rflow workflow. No
networks, no signer: neither embedded engine boots.

This is the reference use of the
[`trigger.stream`](/workflows/triggers/stream) WebSocket trigger.

### Honest scope

This is **durable automation, not HFT.** A matched message flows through
rflow's normal path — it claims a run, respects the workflow's throttle and
rate limit, and is journaled with full history and recovery. It is **not** a
low-latency trading engine, and a third-party stream that does not carry a
stable message id is **not** exactly-once (a reconnect can then re-deliver).

### When to use it

* watch a market and page an operator when a symbol crosses a level
* prove a streaming intake path before wiring reads/sends behind it
* turn an exchange/oracle/vendor feed into normal, replayable rflow runs

### How it works

```yaml
# recipe: partial
trigger:
  stream:
    websocket:
      url: ${STREAM_WS_URL}          # e.g. wss://stream.binance.com:9443/ws
      subscribe:
        method: SUBSCRIBE
        params: ["ethusdt@ticker"]
        id: 1
      where: "${{ message.s == 'ETHUSDT' and wei(message.c, 8) > wei('3500', 8) }}"
      idempotency_key: "${{ message.E }}"
      idempotency_ttl: 1h
      heartbeat: 30s
      reconnect:
        min_backoff: 1s
        max_backoff: 60s
      throttle:
        threshold:
          count: 1
          window: 10m
        cooldown: 10m
```

* **`where`** is evaluated over the `message` root (the JSON payload after
  `message_json_path`, default `$`). Only matching messages fire; `false`
  fires nothing. `wei(message.c, 8)` parses the last price (a decimal string)
  to an exact integer so the comparison is precise.
* **`idempotency_key`** makes the feed's event time the claim identity: a
  reconnect that re-delivers the same event within `idempotency_ttl` creates
  **no new run**. Drop it (or point it at a feed without stable ids) and every
  matched message fires a fresh run — documented at-least-once.
* **`throttle`** caps a chatty feed to one alert per 10 minutes while the
  price stays above the level.

### Reliability + redaction

The client connects with a timeout, reconnects with bounded exponential
backoff on any drop, pings on the `heartbeat` interval, and drops any frame
over `max_message_bytes` (default 1 MiB) with a warning. The run payload is
`{ args: <message>, stream: { url_host, received_at } }` — a token in the URL
is redacted to the **host only** and never lands in a payload or a log line.

### Generate it

```bash
rflow new --template price-alert-stream
cd price-alert-stream
cp .env.example .env    # STREAM_WS_URL, TG_BOT_TOKEN, TG_CHAT_ID
docker compose up -d
rflow validate && rflow start
```

### Rehearse offline

```bash
rflow test price-alert --fixture fixtures/ticker-message.json
```

The fixture is the extracted `message` object, so the `where` filter and the
notification run without touching the internet.


## Proxy upgrade alert

**Template:** `proxy-upgrade-alert` · **category:** security · **risk:** `monitor_only`

Watches an ERC1967 proxy for `Upgraded(address implementation)` and notifies
with the **new and previous** implementation address. The previous one comes
from rflow's durable state, written each time an upgrade fires — no archive
node needed.

### When to use it

* you depend on an upgradeable contract you do not control (a stablecoin, a
  bridge, a protocol you integrate)
* you operate upgradeable contracts and want an independent record of every
  implementation change
* as a supply-chain tripwire: an unexpected upgrade is the strongest possible
  signal to pause integrations

### Generate it

```bash
rflow new --template proxy-upgrade-alert
# or add the workflow to an existing project:
rflow add workflow proxy-upgrade-alert
```

Non-interactive (CI/agents):

```bash
rflow new --template proxy-upgrade-alert --yes --output ./usdc-watch \
  --answer proxy_name=USDC --answer proxy_address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
```

### The generated workflow

```yaml
# recipe: partial
workflows:
  proxy-upgrade-alert:
    trigger:
      event:
        contract: USDC
        name: Upgraded
        network: ethereum
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      # the old implementation comes from durable state written on the
      # previous upgrade - 'unknown' on the very first one rflow sees
      - id: alert
        notify:
          channel: ops
          message: "PROXY UPGRADED: USDC implementation is now ${{ trigger.args.implementation }} (was ${{ state['proxy-upgrade-alert.last_impl'] if state['proxy-upgrade-alert.last_impl'] is defined else 'unknown' }}) - tx ${{ trigger.tx_hash }}"
      - id: remember
        state_set:
          key: "proxy-upgrade-alert.last_impl"
          value: "${{ trigger.args.implementation }}"
    on_failure: dead_letter
```

The `Upgraded(address)` signature is shared by OpenZeppelin transparent
proxies, UUPS proxies, and older ZeppelinOS proxies (USDC included), so the
default answers watch mainnet USDC out of the box.

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `proxy-upgrade-alert`                       |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `proxy_name` / `proxy_address`                 | contract / address                      | `USDC` mainnet                              |
| `channel`                                      | string                                  | `ops`                                       |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:`, no `relayers:`, no transactions. The
[`state_set`](/workflows/steps/state-and-lists#state_set) key is namespaced
(`proxy-upgrade-alert.last_impl`) — rename it if you run several proxy
watchers in one project, because state keys are global across workflows.
`on_failure: dead_letter` keeps a failed notification journaled for
`rflow dead-letter` inspection.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + telegram credentials)
rflow validate
rflow start
```

Rehearse without waiting for a real upgrade (dry-run — `state_set` journals
`would_set` and writes nothing):

```bash
rflow test proxy-upgrade-alert --fixture fixtures/upgraded.json
```

### Production checklist

* [ ] `proxy_address` is the **proxy**, not the implementation
* [ ] the proxy actually emits ERC1967 `Upgraded` (transparent/UUPS/legacy
  ZeppelinOS do; some bespoke proxies use different events)
* [ ] telegram credentials in `.env`, test with `rflow test`
* [ ] `rflow validate --preflight` passes against your RPC

### Common modifications

* also watch `AdminChanged` / `BeaconUpgraded` (already in the packaged ABI):
  add a workflow per event
* watch several proxies: one `contracts:` entry + one workflow each, with
  distinct state keys
* gate an automated response on the upgrade: pause your own integration with
  a [`send_transaction`](/workflows/steps/send-transaction) step behind an
  [approval gate](/approvals)


## Relayer low balance alert

**Template:** `relayer-low-balance-alert` · **category:** relayers · **risk:** `monitor_only`

Polls a relayer wallet's **native** balance and alerts a channel once when it
crosses under a floor. The read goes through Multicall3's
`getEthBalance(address)` view — deployed at the same address on 250+ chains —
so no custom contract is needed. No signer, no relayer engine, just a
[read trigger](/workflows/triggers/read) over `eth_call`.

### When to use it

* the wallet that funds your `send_transaction` workflows must never run dry —
  get paged *before* sends start failing
* watch any hot wallet, keeper EOA, or gas tank on any EVM chain
* pair it with the projects that actually send: `rflow add workflow
  relayer-low-balance-alert` into them

### Generate it

```bash
rflow new --template relayer-low-balance-alert
# or into an existing project:
rflow add workflow relayer-low-balance-alert
```

Non-interactive (CI/agents):

```bash
rflow new --template relayer-low-balance-alert --yes --output ./low-balance \
  --answer relayer_address=0x9c5083dd4838e120dbeac44c052179692aa5dac5 \
  --answer min_balance=1.5 --answer poll_interval=5m
```

### The generated YAML

```yaml
# recipe: partial
workflows:
  relayer-low-balance-alert:
    trigger:
      read:
        contract: Multicall3
        network: ethereum
        function: "getEthBalance(address)"
        args: ["0x9c5083dd4838e120dbeac44c052179692aa5dac5"]
        every: 1m
        condition: "${{ output < wei('0.5', 18) }}"
        mode: threshold
    steps:
      - id: alert
        notify:
          channel: ops
          message: "relayer hot-wallet (0x9c50...dac5) is under the 0.5 ETH floor: ${{ format_units(trigger.args.output, 18) }} ETH left - top it up before sends start failing"
    on_failure: dead_letter
```

### Inputs

| key                                            | type                                    | default                                        |
| ---------------------------------------------- | --------------------------------------- | ---------------------------------------------- |
| `project_name`                                 | string                                  | `relayer-low-balance-alert`                    |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC    |
| `relayer_name` / `relayer_address`             | string / address                        | `hot-wallet` / **required**                    |
| `min_balance`                                  | decimal                                 | `0.5` (whole native tokens)                    |
| `native_symbol` / `native_decimals`            | string / int                            | `ETH` / `18`                                   |
| `poll_interval`                                | duration                                | `1m`                                           |
| `multicall_address`                            | address                                 | the canonical Multicall3 (same on 250+ chains) |
| `channel`                                      | string                                  | `ops`                                          |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:`, no `relayers:` — the relayer engine never boots.
The trigger's `threshold` mode is **edge-triggered and persisted**
(`rflow.read_trigger_state`): one alert on the crossing under the floor, not
one per poll while the balance stays low, and a restart mid-"low" does not
re-page. The alert path ends in `on_failure: dead_letter`, so a failed
notification is journaled, never lost.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + telegram credentials)
rflow validate
rflow start
```

Set `min_balance` above the wallet's real balance and the alert fires on the
first poll (a false→true crossing from the trigger's initial state);
`fixtures/low-balance-fire.json` documents the fire payload the message
renders against.

### Production checklist

* [ ] floor covers your worst gas day: `min_balance` ≥ (sends/day × gas/send
  × a safety factor) — an alert that fires *after* the last send fails is
  decoration
* [ ] `poll_interval` matched to burn rate (1m for busy keepers, 15m for a
  quiet treasury)
* [ ] the alert lands on a channel someone acts on — pagerduty via
  `rflow add notification` if telegram is too quiet
* [ ] one watcher per funded wallet: repeat `rflow add workflow
      relayer-low-balance-alert --name <wallet> --answer relayer_address=0x...`
* [ ] add [`workflow-error-pager`](/use-cases/workflow-error-pager) so a
  dead-lettered *alert* run also pages

### Common modifications

* watch an ERC20 gas token instead: point the contract at the token with
  `balanceOf(address)` and set `native_decimals` accordingly
* non-18-decimal natives: set `native_decimals` (the condition and the
  message format through it)
* alert into a funding runbook: swap `notify:` for an `http_call:` to your
  ops automation — or graduate to a money-moving top-up workflow behind an
  [approval gate](/approvals)
* add a second, lower "critical" floor as another workflow with a pagerduty
  channel


## Safe multisig monitor

**Template:** `safe-monitor` · **category:** security · **risk:** `monitor_only`

Watches a Safe multisig for the events that matter: `AddedOwner`,
`RemovedOwner`, `ChangedThreshold`, and `ExecutionSuccess` (optionally only
above a gas-refund threshold). Owner-set and threshold changes only happen
when the multisig itself is being rewired — exactly the events you want a
human paged on within seconds.

### When to use it

* your treasury, protocol admin, or ops funds sit behind a Safe
* you want an independent alert channel that does not depend on the Safe UI
* as a compromise tripwire: an attacker adding an owner or dropping the
  threshold shows up immediately

### Generate it

```bash
rflow new --template safe-monitor
```

Non-interactive (CI/agents):

```bash
rflow new --template safe-monitor --yes --output ./safe-watch \
  --answer safe_address=0xYourSafe --answer safe_version=1.4
```

### What it generates

Four event-triggered workflows over one `contracts:` entry:

| workflow                 | event              | notifies                        |
| ------------------------ | ------------------ | ------------------------------- |
| `safe-owner-added`       | `AddedOwner`       | the new owner address           |
| `safe-owner-removed`     | `RemovedOwner`     | the removed owner address       |
| `safe-threshold-changed` | `ChangedThreshold` | the new signature threshold     |
| `safe-execution`         | `ExecutionSuccess` | safeTxHash + gas-refund payment |

```yaml
# recipe: partial
workflows:
  safe-owner-added:
    trigger:
      event:
        contract: TreasurySafe
        name: AddedOwner
        network: ethereum
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: alert
        notify:
          channel: ops
          message: "SAFE OWNER ADDED on TreasurySafe: ${{ trigger.args.owner }} - tx ${{ trigger.tx_hash }}"
    on_failure: dead_letter

  safe-execution:
    trigger:
      event:
        contract: TreasurySafe
        name: ExecutionSuccess
        network: ethereum
        # payment is the gas refund the Safe paid; 0 = notify on EVERY execution
        where: "${{ trigger.args.payment >= wei('0', 18) }}"
        ...
```

### Inputs

| key                                            | type                                    | default                                                                              |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| `project_name`                                 | string                                  | `safe-monitor`                                                                       |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC                                          |
| `safe_name`                                    | contract                                | `TreasurySafe`                                                                       |
| `safe_address`                                 | address                                 | zero placeholder — **replace it**                                                    |
| `safe_version`                                 | choice `1.3` \| `1.4`                   | `1.3` — v1.4 Safes index `owner`/`txHash`, pick the ABI that matches your deployment |
| `min_payment`                                  | token\_amount                           | `0` (whole native tokens; every execution notifies)                                  |
| `channel`                                      | string                                  | `ops`                                                                                |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:`, no `relayers:`, no transactions — the relayer
engine never boots. Every workflow ends in `on_failure: dead_letter` so a
failed notification is journaled, never lost. Triggers fire at head
(`confirmations: 0`): for a security tripwire you want the earliest possible
signal, and a false alert from a reorged-out event is a feature, not a bug.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + telegram credentials)
rflow validate
rflow start
```

Rehearse the alerts without touching a real Safe (dry-run, nothing sent):

```bash
rflow test safe-owner-added --fixture fixtures/owner-added.json
rflow test safe-execution --fixture fixtures/execution-success.json
```

### Production checklist

* [ ] `safe_address` points at your real Safe (not the zero placeholder)
* [ ] `safe_version` matches the deployed Safe (`1.4` indexes `owner`/`txHash`;
  the wrong ABI means events will not decode)
* [ ] telegram credentials in `.env`, test with `rflow test`
* [ ] the channel pages a human, not a muted group
* [ ] `rflow validate --preflight` passes against your RPC

### Common modifications

* watch several Safes: duplicate the `contracts:` entry and point extra
  workflows at it, or run `rflow new` per Safe
* alert on failed executions too: add a workflow on `ExecutionFailure`
  (already in the packaged ABI)
* raise `min_payment` to only see executions with a meaningful gas refund
* route owner changes to pagerduty and executions to telegram: add a second
  channel with `rflow add notification`


## Safe owner change alert

**Template:** `safe-owner-change-alert` · **category:** security · **risk:** `monitor_only`

Pages the moment a Safe multisig is rewired: `AddedOwner`, `RemovedOwner` and
`ChangedThreshold`. The owner-add/remove alerts read the CURRENT
`getThreshold()` so you see the resulting m-of-n in the same message. A focused
governance watch — see [`safe-monitor`](/use-cases/safe-monitor) when you also
want execution and module events.

### When to use it

* know instantly when a treasury multisig's owner set or threshold changes
* catch an unauthorized owner addition (a compromised signer)
* a lightweight governance watch with no bundled ABI blob

### Generate it

```bash
rflow new --template safe-owner-change-alert

# or add the workflow to an existing project
rflow add workflow safe-owner-change-alert
```

Non-interactive (CI/agents):

```bash
rflow new --template safe-owner-change-alert --yes --output ./safe \
  --answer safe_address=0x0000000000000000000000000000000000000000
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `safe-owner-change-alert`                   |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `safe_name` / `safe_address`                   | contract / address                      | `Safe` / zero placeholder (replace!)        |
| `channel`                                      | string                                  | `ops`                                       |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The Safe v1 ABI is materialized from the builtin standard (v1.3 and
v1.4 share these event signatures), and every workflow ends in
`on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, set safe_address
rflow validate
rflow start
```

### Common modifications

* add a `ChangedThreshold`-only project for the strictest change alarm
* swap the channel for slack/discord/pagerduty: `rflow add notification`
* graduate to [`safe-monitor`](/use-cases/safe-monitor) for execution events


## Security advisory watch

**Template:** `security-advisory-watch` · **category:** security · **risk:** `monitor_only`

Poll an RSS/Atom security feed on an interval and page a channel on every
**new** advisory whose title matches a keyword — deduped on the advisory
link, so an edited advisory never pages twice, and the first poll only
records a baseline (booting on an established feed does not page its
history). No networks, no signer: neither embedded engine boots.

This is the reference use of the [`trigger.web`](/workflows/triggers/web)
HTTP polling trigger.

### Honest scope

**Web signal, not browser automation.** rflow fetches and parses the feed
(with an `rflow/<version>` User-Agent, a 30s timeout and a 2 MiB body cap) —
it never logs in, clicks, or drives a browser. Respect the feed operator's
robots.txt and rate limits: poll no faster than the feed actually updates.

### When to use it

* page the on-call when a dependency posts a critical security advisory
* watch a protocol's announcements feed for pause/upgrade/incident notices
* turn any RSS/Atom feed into deduped, journaled, replayable rflow runs

### How it works

```yaml
# recipe: partial
trigger:
  web:
    url: https://example.com/security/feed.xml
    every: 5m
    mode: rss
    where: "${{ 'critical' in (item.title | lower) }}"
    idempotency_key: "${{ item.link }}"
```

* **`where`** is evaluated per feed entry over the `item` root
  (`{ id, title, link, published, summary }`). Only matching entries fire.
* **`idempotency_key`** makes the advisory's link the claim identity: an
  edited advisory (same link, touched title) creates **no second run**. Drop
  it and the dedupe key falls back to the item's content fingerprint — then
  an edit counts as a new item.
* The message template reads the fired entry directly:
  `"Security advisory: ${{ item.title }} ${{ item.link }}"`.

### Generate it

```bash
rflow new --template security-advisory-watch
cd security-advisory-watch
cp .env.example .env    # DATABASE_URL + pager credentials
docker compose up -d
rflow validate && rflow start
```

Non-interactive:

```bash
rflow new --template security-advisory-watch --yes \
  --answer feed_url=https://example.com/security/feed.xml \
  --answer match_keyword=critical \
  --answer pager=pagerduty
```

### Inputs

| key             | type                               | default                                 |
| --------------- | ---------------------------------- | --------------------------------------- |
| `project_name`  | string                             | `security-advisory-watch`               |
| `feed_url`      | string                             | `https://example.com/security/feed.xml` |
| `feed_mode`     | choice (`rss` \| `atom`)           | `rss`                                   |
| `poll_every`    | duration                           | `5m` (floor 30s)                        |
| `match_keyword` | string                             | `critical`                              |
| `channel`       | string                             | `pager`                                 |
| `pager`         | choice (`pagerduty` \| `telegram`) | `pagerduty`                             |

### Required env vars

`DATABASE_URL`, plus `PAGERDUTY_ROUTING_KEY` **or** `TG_BOT_TOKEN` +
`TG_CHAT_ID` depending on the `pager` choice.

### Rehearse offline

```bash
rflow test security-advisory-watch --fixture fixtures/advisory-item.json
```

The fixture is one parsed feed entry (`{ "item": {...} }`), so the page text
renders without touching the live feed.

### Common modifications

* watch a JSON API instead: `mode: json` with `path: "$.advisories"`
* watch a status page: `mode: html_text` with `selector: ".incident"` and
  `changed: true` (fire on any change rather than per new item)
* authenticated feeds: add
  `headers: { Authorization: "Bearer ${{ secrets.feed_token }}" }` — header
  values are never journaled or logged


## Solver inventory rebalance

**Template:** `solver-inventory-rebalance` · **category:** intents · **risk:** `money_moving`

Keeps a solver's fill wallet stocked. It polls the solver wallet's ERC20
inventory and, when the balance drifts below a floor, parks a top-up transfer
from a separate `funding` wallet behind a human approval — refilling the
solver back to a target balance. The pairing for
[`erc7683-solver`](/use-cases/erc7683-solver): the fill workflow burns
output-token inventory, this keeps it topped up.

### When to use it

* your solver runs out of a token mid-day and starts skipping fills
* you want a human in the loop before reserve capital moves to the hot wallet
* you keep funding capital in a separate wallet from the fill wallet

### Generate it

```bash
rflow new --template solver-inventory-rebalance

# or add the workflow to an existing project
rflow add workflow solver-inventory-rebalance
```

Non-interactive (CI/agents):

```bash
rflow new --template solver-inventory-rebalance --yes --output ./rebalance \
  --answer token_address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  --answer min_inventory=50000 --answer refill_to=100000
```

### Inputs

| key                                               | type                                    | default                                     |
| ------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                    | string                                  | `solver-inventory-rebalance`                |
| `network` / `chain_id` / `rpc_env` / `rpc_url`    | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `confirmations`                                   | int                                     | `3`                                         |
| `token_name` / `token_address` / `token_decimals` | contract / address / int                | `Token` / USDC mainnet / `6`                |
| `solver_wallet`                                   | address                                 | zero placeholder (replace!)                 |
| `min_inventory` / `refill_to`                     | token\_amount                           | `50000` / `100000`                          |
| `poll_every`                                      | duration                                | `1m`                                        |
| `approval_timeout`                                | duration                                | `30m`                                       |
| `gas_max_price`                                   | string                                  | `50 gwei`                                   |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), and
`RAW_DANGEROUS_MNEMONIC` — `rflow new` writes a fresh DEV-ONLY mnemonic;
swap in a production signer before real funds ride on it.

### Safety notes

Money-moving, so every rail is on: pre-flight simulation with
`assert_sim: ["${{ sim.ok }}"]`, a `gas.max_price` ceiling, a concurrency
group (`skip`) so a parked top-up never stacks, `wait_for: confirmed`, and
`on_failure: dead_letter`. The top-up is parked behind
[approval](/approvals) — `rflow approve <id>` — and the approval
re-simulates immediately before broadcast, so a wallet refilled during the
wait sends nothing. Attach a [budget](/workflows/budgets) to cap cumulative
top-up spend.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + a real signer), set solver_wallet
rflow validate
rflow start
```

### Common modifications

* refill from an external treasury by pointing `funding` at that wallet
* watch several tokens by adding a workflow per token
* raise `poll_every` on quiet chains to cut RPC load


## Solver PnL report

**Template:** `solver-pnl-report` · **category:** intents · **risk:** `monitor_only`

A cron report over your solver's OWN journal. Each schedule tick it queries
rflow's Postgres journal for the named fill workflow and posts a one-line
summary: intents seen, how many filled, how many skipped/raced, how many
failed, and the native value the fills moved (the journaled send `value` —
not gas cost; gas lives in the [spend ledger](/operations/spend-tracking)).
Point it at the same database your solver
writes to. Monitor-only: no networks, no signer — it reads `rflow.*` and
notifies.

### When to use it

* a nightly / hourly digest of solver activity without a separate dashboard
* turn skipped/raced orders into a visible number instead of silent no-ops
* track fills and native value moved from the journal, no extra
  instrumentation (for gas cost, use `rflow spend` / the spend ledger)

### Generate it

```bash
rflow new --template solver-pnl-report

# or add the workflow to an existing project
rflow add workflow solver-pnl-report
```

Non-interactive (CI/agents):

```bash
rflow new --template solver-pnl-report --yes --output ./pnl \
  --answer fill_workflow=fill-intent --answer report_window="24 hours"
```

### Inputs

| key             | type                 | default             |
| --------------- | -------------------- | ------------------- |
| `project_name`  | string               | `solver-pnl-report` |
| `fill_workflow` | string               | `fill-intent`       |
| `report_cron`   | cron                 | `0 * * * *`         |
| `report_window` | string (pg interval) | `1 hour`            |
| `native_symbol` | string               | `ETH`               |
| `channel`       | string               | `ops`               |

### Required env vars

`DATABASE_URL` (the same database your solver writes to), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `networks:` and no `signer:`, so neither embedded engine
boots. The query runs read-only inside a Postgres `READ ONLY` transaction.
It reads only the always-present journal (`rflow.workflow_runs`,
`rflow.step_runs`) — it does NOT depend on any native-spend-tracking tables.
The workflow ends in `on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, point DATABASE_URL at your solver's database
rflow validate
rflow start
```

### Common modifications

* add token-inventory PnL by joining your indexed settlement `Filled` rows
* swap the channel for slack/discord/pagerduty: `rflow add notification`
* widen `report_window` for a daily digest


## Stablecoin pause / blacklist monitor

**Recipe** (no bundled template) · **category:** monitoring · **risk:** `monitor_only`

Page the moment a stablecoin issuer freezes the token or blacklists an
address. Centrally-controlled stablecoins (USDC/USDT-style) can `pause()` all
transfers or `blacklist` a specific account — if your protocol holds or routes
that token, you want to know *before* your next transfer reverts. This recipe
watches the issuer's `Paused` / `Unpaused` / `Blacklisted` events **and** keeps
a `paused()` read as a backstop in case a log is missed.

Closest bundled starting point: the
[large transfer alert](/use-cases/large-transfer-alert) template — the same
no-signer, event → notify shape. Swap its ABI + events for the ones below.

### When to use it

* you custody or route a centrally-controlled stablecoin (USDC, USDT, …)
* you want to freeze your own flows the instant the issuer pauses the token
* you need to know if one of your addresses gets blacklisted

### The config

Four workflows, one contract, no signer. Each event workflow is a thin
notify; the fourth is a `read`-trigger backstop that pages if `paused()` ever
reads `true`.

```yaml
# recipe: full
rflow_version: 1
name: stablecoin-pause-monitor

config:
  port: 3948
  db_connection: ${DATABASE_URL}

# monitor-only: no signer and no relayers, so neither embedded engine boots.
# The event workflows index the token; the read workflow polls over eth_call.
networks:
  - name: ethereum
    chain_id: 1
    rpc: ${ETH_RPC}

contracts:
  # a USDC/USDT-style token that exposes Pausable + a blacklist. Swap in the
  # real token address and an ABI carrying its pause/blacklist events.
  Stablecoin:
    abi: ./abis/stablecoin.json
    addresses:
      ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

notifications:
  channels:
    ops:
      telegram:
        bot_token: ${TG_BOT_TOKEN}
        chat_id: ${TG_CHAT_ID}

workflows:
  # the token was paused - every transfer is now frozen. Page immediately.
  stablecoin-paused:
    trigger:
      event:
        contract: Stablecoin
        name: Paused
        network: ethereum
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: alert
        notify:
          channel: ops
          message: "STABLECOIN PAUSED on ethereum by ${{ trigger.args.account }} - all transfers frozen (tx ${{ trigger.tx_hash }})"
    on_failure: dead_letter

  # the token was unpaused - transfers resume.
  stablecoin-unpaused:
    trigger:
      event:
        contract: Stablecoin
        name: Unpaused
        network: ethereum
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: alert
        notify:
          channel: ops
          message: "stablecoin UNPAUSED on ethereum by ${{ trigger.args.account }} - transfers resumed (tx ${{ trigger.tx_hash }})"
    on_failure: dead_letter

  # an address was blacklisted - its balance is frozen. If it is one of yours,
  # you want to know before your next transfer reverts.
  stablecoin-blacklisted:
    trigger:
      event:
        contract: Stablecoin
        name: Blacklisted
        network: ethereum
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: alert
        notify:
          channel: ops
          message: "stablecoin BLACKLISTED ${{ trigger.args.account }} on ethereum (tx ${{ trigger.tx_hash }})"
    on_failure: dead_letter

  # backstop: even if a Paused log is missed, this read trigger pages the
  # moment paused() first reads true (false->true crossing, edge-triggered)
  stablecoin-paused-backstop:
    trigger:
      read:
        contract: Stablecoin
        network: ethereum
        function: "paused()"
        every: 1m
        condition: "${{ output == true }}"
        mode: threshold
    steps:
      - id: alert
        notify:
          channel: ops
          message: "stablecoin paused() reads TRUE on ethereum - transfers are frozen"
    on_failure: dead_letter
```

### Required env vars

`DATABASE_URL`, `ETH_RPC`, `TG_BOT_TOKEN`, `TG_CHAT_ID`.

### Safety notes — monitor-only

* **No signer, no relayers** — the config declares neither, so the relayer
  engine never boots and this workflow can only ever *read and notify*.
* `on_failure: dead_letter` journals a failed notification instead of losing
  it — a paged alert you can replay.
* `confirmations: 0` favours latency (you want a pause alert *now*); a pause
  in a reorged block would re-alert on the canonical block. Raise it if you
  prefer certainty over speed. The `paused()` backstop covers a missed log.
* The bundled `stablecoin.json` here carries generic `Paused(address)` /
  `Unpaused(address)` / `Blacklisted(address)` events; real issuers differ
  (USDT uses `Pause()`/`Unpause()` with no args and `AddedBlackList(address)`).
  Fetch the real ABI (`rflow abi fetch`) and adjust the event names.

### Common modifications

* **Escalate a pause** to PagerDuty/Opsgenie instead of telegram — add the
  channel (`rflow add notification`) and point the `paused` workflow at it.
* **Only my addresses**: filter `stablecoin-blacklisted` with a
  `where: "${{ lower(trigger.args.account) in constants.mine }}"` over a
  [list](/workflows/steps/state-and-lists) of your addresses.
* **Freeze your own flows**: have the `paused` workflow flip a
  [`state:`](/workflows/steps/state-and-lists) flag your money workflows gate
  on with an `if:`.


## Timelock monitor

**Template:** `timelock-monitor` · **category:** governance · **risk:** `monitor_only`

Watches an OpenZeppelin `TimelockController` and notifies when an operation is
**scheduled** (with decoded target, value, and delay), **executed**, or
**cancelled**. The scheduled alert is the important one: the delay window is
the whole point of a timelock, and this template pages you while there is
still time to react.

### When to use it

* your protocol's admin functions sit behind a timelock and you want every
  queued operation in front of humans immediately
* you are a token holder / integrator watching someone else's governance
* as part of an incident-response plan: "who watches the timelock?" — this does

### Generate it

```bash
rflow new --template timelock-monitor
```

Non-interactive (CI/agents):

```bash
rflow new --template timelock-monitor --yes --output ./gov-watch \
  --answer timelock_address=0xYourTimelock
```

### What it generates

Three event-triggered workflows over one `contracts:` entry:

| workflow                  | event           | notifies                                   |
| ------------------------- | --------------- | ------------------------------------------ |
| `timelock-call-scheduled` | `CallScheduled` | decoded target, value, delay, operation id |
| `timelock-call-executed`  | `CallExecuted`  | target, value, operation id                |
| `timelock-cancelled`      | `Cancelled`     | operation id                               |

```yaml
# recipe: partial
workflows:
  timelock-call-scheduled:
    trigger:
      event:
        contract: Timelock
        name: CallScheduled
        network: ethereum
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: alert
        notify:
          channel: ops
          message: "timelock SCHEDULED on Timelock: target ${{ trigger.args.target }}, value ${{ format_units(trigger.args.value, 18) }} native, executable in ${{ trigger.args.delay }}s - id ${{ trigger.args.id }} tx ${{ trigger.tx_hash }}"
    on_failure: dead_letter
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `timelock-monitor`                          |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `timelock_name`                                | contract                                | `Timelock`                                  |
| `timelock_address`                             | address                                 | zero placeholder — **replace it**           |
| `channel`                                      | string                                  | `ops`                                       |

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:`, no `relayers:`, no transactions. Batched
timelock operations emit one `CallScheduled` **per call** (same `id`,
increasing `index`) — a big batch produces several notifications, which is
usually what you want for governance review. Every workflow ends in
`on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (RPC + telegram credentials)
rflow validate
rflow start
```

Rehearse without a real proposal (dry-run, nothing sent):

```bash
rflow test timelock-call-scheduled --fixture fixtures/call-scheduled.json
```

### Production checklist

* [ ] `timelock_address` points at the real TimelockController (not the zero
  placeholder)
* [ ] the contract is an OZ `TimelockController` (Compound-style `Timelock`
  uses different events — `QueueTransaction`/`ExecuteTransaction`)
* [ ] telegram credentials in `.env`, test with `rflow test`
* [ ] the channel reaches whoever can actually veto/cancel in time
* [ ] `rflow validate --preflight` passes against your RPC

### Common modifications

* alert on `MinDelayChange` too (already in the packaged ABI) — a shrinking
  delay is itself a governance event worth paging on
* decode the scheduled calldata further in the message with
  [`abi_encode`](/workflows/expressions#functions) comparisons, or forward
  `trigger.args.data` to an [`http_call`](/workflows/steps/http-call) for
  off-chain decoding
* track open operations in a [list](/workflows/steps/state-and-lists):
  `list_add` the id on schedule, `list_remove` on execute/cancel


## Token deposit relay

**Template:** `token-deposit-relay` · **category:** relayers · **risk:** `money_moving`

An ERC20 `Transfer` **into** a watched deposit address (at or above a minimum
amount) triggers a relayed payout of the same amount from the `payout`
wallet — the classic exchange/treasury deposit-echo pattern. Runnable sibling:
[`examples/token-transfer-relay`](https://github.com/joshstevens19/rflow/tree/master/examples/token-transfer-relay).

### When to use it

* credit or forward user deposits to a downstream address automatically
* bridge-style "mirror this deposit elsewhere" flows on a single chain
* any event-driven send where the amount comes straight from the trigger

### Generate it

```bash
rflow new --template token-deposit-relay
# or into an existing project (needs a signer; adds the `payout` relayer):
rflow add workflow token-deposit-relay
```

### What the generated YAML does

1. **Trigger** — `Transfer` events on the token, filtered in `where:` to
   deposits `>= min_deposit` whole tokens whose `to` is the watched
   `deposit_address`. The network's `confirmations: 12` means a reorged
   deposit never pays out.
2. **`gate`** — reads `balanceOf(payout relayer)` and asserts the wallet can
   cover the deposit (a short wallet fails the run into the dead-letter
   queue instead of firing a doomed send).
3. **`payout`** — `transfer(payout_address, trigger.args.value)` through the
   embedded relayer: simulated first (`assert_sim: sim.ok`), gas-capped,
   then held until `confirmed`. The simulation is also the drained-wallet
   guard — a transfer the wallet cannot cover reverts in `eth_call` and
   dead-letters instead of broadcasting.

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `token-deposit-relay`                       |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `confirmations`                                | int                                     | `12`                                        |
| `token_address` / `token_decimals`             | address / int                           | USDC mainnet / `6`                          |
| `deposit_address`                              | address                                 | zero placeholder — **replace it**           |
| `payout_address`                               | address                                 | zero placeholder — **replace it**           |
| `min_deposit`                                  | token\_amount                           | `100`                                       |
| `gas_max_price`                                | string                                  | `100 gwei`                                  |

### Required env vars

`DATABASE_URL`, the RPC env var, `RAW_DANGEROUS_MNEMONIC`. `rflow new` fills
`.env` with a freshly generated DEV-ONLY mnemonic — swap in a production
signer before real funds ride on this config.

### Safety defaults (all generated)

* inventory gate (`read` + `assert`) before any send
* pre-flight simulation + `assert_sim: ["${{ sim.ok }}"]` — this is the
  drained-wallet guard: an uncoverable transfer reverts in simulation
  instead of broadcasting (a `recheck` would only re-test journaled
  constants the gate already passed, so the template ships none)
* gas cap: `limit_from_simulation` + `max_price`
* network `confirmations: 12`, `wait_for: confirmed`
* `concurrency.on_conflict: queue` — payouts are serialized, never racing
  the same wallet balance
* `on_failure: dead_letter`

### Run it locally

```bash
docker compose up -d           # postgres on :5448
rflow validate                 # should be green out of the box
rflow test token-deposit-relay --fixture fixtures/deposit-event.json  # dry-run rehearsal
rflow start                    # go live
```

The generated `fixtures/deposit-event.json` is a 250-token deposit into your
watched address — edit `value` to rehearse the `min_deposit` boundary.

### Production checklist

1. replace the `deposit_address` and `payout_address` placeholders
2. replace the raw dev mnemonic with a production signer
3. fund the `payout` relayer with tokens AND gas
4. dry-run the fixture, then watch the first live deposit in `rflow runs ls`
5. consider a budget on the workflow if you run budgets

### Common modifications

* **Alert instead of failing** when inventory is short: drop the `assert`
  on `gate` and add a `notify` step behind an `if:`.
* **Fee-taking relay**: pay out `trigger.args.value * 99 / 100` instead of
  the full amount.
* **Multiple deposit addresses**: move `deposit_address` into a `list:` and
  match with `contains(...)` in the trigger `where:`.
* **Idle-deposit sweep**: pair it with
  [`treasury-sweep-approval`](/use-cases/treasury-sweep-approval) to move
  accumulated balances to cold storage behind an approval.


## Treasury sweep with approval

**Template:** `treasury-sweep-approval` · **category:** treasury · **risk:** `money_moving`

A cron reads a hot treasury wallet's ERC20 balance; above a threshold the
sweep to cold storage is prepared, simulated and **parked behind a human
approval** (`rflow approvals ls`, `rflow approve <id>`). Runnable sibling:
[`examples/treasury-ops`](https://github.com/joshstevens19/rflow/tree/master/examples/treasury-ops).

### When to use it

* keep hot-wallet balances low without a human doing the transfer by hand
* any recurring send where a person must stay in the loop

### Generate it

```bash
rflow new --template treasury-sweep-approval
# or into an existing project (needs a signer; adds the `treasury` relayer):
rflow add workflow treasury-sweep-approval
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `treasury-ops`                              |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `token_address` / `token_decimals`             | address / int                           | USDC mainnet / `6`                          |
| `cold_storage`                                 | address                                 | zero placeholder — **replace it**           |
| `min_sweep_amount`                             | token\_amount                           | `1000`                                      |
| `sweep_cron`                                   | cron                                    | `0 * * * *` (hourly)                        |
| `approval_timeout`                             | duration                                | `1h`                                        |
| `gas_max_price`                                | string                                  | `100 gwei`                                  |

### Required env vars

`DATABASE_URL`, the RPC env var, `RAW_DANGEROUS_MNEMONIC`. `rflow new` fills
`.env` with a freshly generated DEV-ONLY mnemonic — swap in a production
signer before real funds ride on this config.

### Safety defaults (all generated)

* pre-flight simulation + `assert_sim: ["${{ sim.ok }}"]`
* gas cap: `limit_from_simulation` + `max_price`
* post-approval re-simulation — approve re-prepares + re-simulates, so a
  wallet drained during the wait reverts and dead-letters instead of firing
  stale (no `recheck`: expressions only see the journaled balance read,
  which cannot change while the run is parked)
* approval gate `via: [cli]`, `on_timeout: fail`
* `confirmations: 12` on the network, `wait_for: confirmed`
* `concurrency.on_conflict: skip` — one sweep in flight at a time
* `on_failure: dead_letter`

### Production checklist

1. replace the `cold_storage` placeholder with the real address
2. replace the raw dev mnemonic with a production signer
3. add a second approval route (`via: [telegram: ops, cli]`)
4. dry-run it first: `rflow test treasury-sweep-approval --cron-at <tick>`


## Uniswap v2 price alert

**Template:** `community/uniswap-v2-price-alert` · **category:** monitoring · **risk:** `monitor_only` · **community**

Watches a Uniswap v2 pair's `Sync` event — emitted on every reserve change —
and notifies a telegram channel when the reserve-derived spot price leaves a
band. No signer, no relayer, no transactions.

Community template: it lives under `templates/community/` in the rflow repo
(not in the binary) and is fetched SHA-pinned and hash-verified at install
time. The package ships NO ABI blob — the manifest declares the `pair`
interface against the curated builtin `uniswap-v2-pair` standard, and the
install materializes `abis/pair.json` from it after verifying the
`Sync(uint112,uint112)` topic0.

### When to use it

* alert on a spot-price breakout for a token that lives on a v2 pool
* watch a long-tail pair no oracle covers
* a template for your own first community submission (see
  `templates/community/SUBMITTING.md`)

### Generate it

```bash
# a full project (fetched from the registry, hash-verified, then gated)
rflow new --template community/uniswap-v2-price-alert

# or add the workflow to an existing project
rflow add workflow community/uniswap-v2-price-alert

# browse the community index first
rflow templates ls --community
```

Non-interactive (CI/agents):

```bash
rflow new --template community/uniswap-v2-price-alert --yes --output ./v2 \
  --answer price_low=1000 --answer price_high=5000
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `uniswap-v2-price-alert`                    |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `pair_name` / `pair_address`                   | contract / address                      | `Pair` / zero placeholder (replace!)        |
| `token0_decimals` / `token1_decimals`          | int                                     | `18` / `6`                                  |
| `price_low` / `price_high`                     | decimal                                 | `1000` / `5000`                             |
| `channel`                                      | string                                  | `ops`                                       |
| `tg_bot_token_env` / `tg_chat_id_env`          | env\_var                                | `TG_BOT_TOKEN` / `TG_CHAT_ID`               |

Price is `reserve1 * 10^token0_decimals / reserve0` (token1 per 1 whole
token0), computed with `mul_div`. It assumes a non-empty pool.

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), and the telegram
credentials (default `TG_BOT_TOKEN` / `TG_CHAT_ID`) — all in the generated
`.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The install records the registry, commit and per-file sha256s in
`.rflow/template-lock.yaml`, and the workflow ends in
`on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, set the pair address + decimals + band
rflow validate
rflow start
```

### Common modifications

* flip `token0`/`token1` if the price reads inverted for your pair
* widen the band, or add a second pair as another workflow
* pair with the [WETH wrap monitor](/use-cases/weth-wrap-monitor) on the same book


## Uniswap v3 LP monitor

**Template:** `uniswap-v3-lp-monitor` · **category:** monitoring · **risk:** `monitor_only`

Tells you the moment a Uniswap v3 pool's price tick leaves the range your LP
position earns in. Two workflows on one pool: `lp-swap-out-of-range` watches
`Swap` events (each carries the post-swap tick) for an instant page, and
`lp-slot0-out-of-range` polls `slot0()` and fires once on the crossing — a
safety net that catches a range exit even if the event stream was down.

### When to use it

* know the second your concentrated liquidity stops earning fees
* catch a range exit that happened while your indexer was catching up
* a base for a rebalancing keeper (add a send once you trust the signal)

### Generate it

```bash
rflow new --template uniswap-v3-lp-monitor

# or add the workflow to an existing project
rflow add workflow uniswap-v3-lp-monitor
```

Non-interactive (CI/agents):

```bash
rflow new --template uniswap-v3-lp-monitor --yes --output ./lp \
  --answer tick_lower=-60000 --answer tick_upper=60000
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `uniswap-v3-lp-monitor`                     |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `pool_name` / `pool_address`                   | contract / address                      | `Pool` / zero placeholder (replace!)        |
| `tick_lower` / `tick_upper`                    | int                                     | `-60000` / `60000`                          |
| `poll_every`                                   | duration                                | `1m`                                        |
| `channel`                                      | string                                  | `ops`                                       |

Ticks are signed — negative ticks are normal for low prices. Read
`tick_lower` / `tick_upper` off your LP NFT, or use a wide band to watch the
whole pool.

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), `TG_BOT_TOKEN`,
`TG_CHAT_ID` — all listed in the generated `.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The poll workflow is edge-triggered (fires once on the crossing out of
range), and both workflows end in `on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env, set pool_address + the tick range
rflow validate
rflow start
```

### Common modifications

* widen the band to a whole-pool price-move alarm
* add a second pool by copying the two workflows
* extend into a rebalancer: add an approval-gated `send_transaction`


## Webhook idempotent handler

**Template:** `webhook-idempotent-handler` · **category:** offchain · **risk:** `prepares_tx`

An HMAC-authenticated webhook feeds a project-owned node script that
validates the request, derives a **deterministic dedupe key**, and prepares an
ERC20 transfer **as data**; rflow notifies a channel with the decision.
`prepares_tx` honestly: transaction calldata is produced, but the project has
no signer and no relayer — nothing in it can broadcast.

### When to use it

* accept transfer/payout requests from another system without giving that
  system a key
* put validation + policy (caps, allowlists) in YOUR code while rflow owns
  authentication, durability and the audit trail
* the safe precursor to a relaying flow: prove the intake path first, add the
  send step later

### The idempotency story

Two layers, each owning a different window:

* **the trigger dedupes deliveries** —
  [`idempotency_key`](/workflows/triggers/webhook#idempotency--dedupe-caller-retries)
  makes the caller's `intent_id` the claim identity: a retry of the **same
  intent** within `idempotency_ttl` (7d) creates **no new run** and answers
  `200 {"status":"duplicate","run_id":<original>,"run_status":...}`; a body
  without an `intent_id` is a `400` and never starts a run
* **`request_key` dedupes downstream** — the TTL is a re-use window, not
  retention: `request_key` is a pure function of the body
  (`sha256(intent_id | to | amount)` truncated), so a post-TTL replay yields
  the **same key on a new run**; every notification leads with it, and
  anything consuming the prepared payload must dedupe on `request_key`,
  never on the run id

### Generate it

```bash
rflow new --template webhook-idempotent-handler
# or into an existing project:
rflow add workflow webhook-idempotent-handler
```

### Inputs

| key              | type          | default                                              |
| ---------------- | ------------- | ---------------------------------------------------- |
| `project_name`   | string        | `webhook-idempotent-handler`                         |
| `webhook_path`   | string        | `/hooks/transfer-request`                            |
| `secret_env`     | env\_var      | `WEBHOOK_SECRET`                                     |
| `max_amount`     | token\_amount | `10000` (whole tokens; larger requests are rejected) |
| `token_decimals` | int           | `6` (amounts arrive in base units)                   |
| `channel`        | string        | `ops`                                                |

### Generated YAML (the shape)

```yaml
# recipe: partial
trigger:
  webhook:
    path: /hooks/transfer-request
    auth: hmac                       # rflow verifies the body signature
    secret: "${{ secrets.webhook }}"
    idempotency_key: "${{ body.intent_id }}"  # retries dedupe BEFORE a run exists
    idempotency_ttl: 7d
    on_duplicate: return_existing    # 200 + the original run id
steps:
  - id: prepare   # validate + dedupe-key + prepare (never signs or sends)
    command:
      run: "node ./scripts/prepare.js"
      timeout: 10s
      output: json
      input: { intent_id: "${{ trigger.args.intent_id }}", to: "${{ trigger.args.to }}", amount: "${{ trigger.args.amount }}", ... }
  - id: alert     # the message leads with the request_key so duplicates show
    notify:
      channel: ops
      message: "[${{ steps.prepare.output.request_key }}] transfer request ... -> ${{ steps.prepare.output.decision }}"
on_failure: dead_letter
```

### Required env vars

`DATABASE_URL`, the HMAC shared secret (default `WEBHOOK_SECRET`), and
`TG_BOT_TOKEN` / `TG_CHAT_ID` for the notification channel — all listed in the
generated `.env.example`. `node` must be on PATH.

### Safety notes

* the webhook is HMAC-authenticated (`auth: hmac`) — unsigned/garbled bodies
  never start a run
* caller retries are deduped at the trigger (`idempotency_key`) — a retried
  `intent_id` within the TTL answers with the original run instead of
  preparing anything twice
* the prepare script enforces a hard `max_amount` cap and address/amount shape
  checks before anything is prepared
* no signer, no relayer: a compromised caller can at worst generate rejected
  requests and notifications
* `on_failure: dead_letter` keeps failed deliveries replayable

### Run it locally

```bash
docker compose up -d
rflow validate
# rehearse a delivery without HTTP:
rflow test webhook-idempotent-handler --fixture fixtures/webhook-request.json
rflow start
# live: POST {"intent_id","to","amount"} to the path, HMAC-SHA256-signed
```

### Production checklist

1. rotate `WEBHOOK_SECRET` and share it only with the calling system
2. make callers send a unique, stable `intent_id` per business action — it
   is the trigger's `idempotency_key` claim identity AND the `request_key`
   input; the dedupe is only as good as its identity field
3. wire the notification channel to a real destination and alert on repeated
   `request_key`s
4. put rflow's port behind your ingress/network controls (HMAC is the app
   layer, not the only layer)

### Common modifications

* extend `prepare.js` with allowlists or a policy call to your own service
* hand the prepared `tx` to a downstream executor — or add a
  `send_transaction:` step plus signer/relayer (with an `approval:` gate) to
  execute in-place, which upgrades the risk to `money_moving`
* swap telegram for slack/pagerduty in the `notifications:` block


## WETH wrap monitor

**Template:** `community/weth-wrap-monitor` · **category:** monitoring · **risk:** `monitor_only` · **community**

Watches WETH9's `Deposit` (wrap) and `Withdrawal` (unwrap) events and notifies
a telegram channel on large ones — a spike in wrapping/unwrapping often
front-runs a big on-chain move. No signer, no relayer, no transactions.

Community template: fetched SHA-pinned and hash-verified at install time. The
package ships NO ABI blob — the manifest declares the `weth` interface against
the curated builtin `weth9` standard, and the install materializes
`abis/weth.json` from it after verifying the declared
`Deposit(address,uint256)` / `Withdrawal(address,uint256)` topic0s.

### When to use it

* watch for large wraps/unwraps ahead of a big swap or bridge
* monitor WETH flow on any chain by pointing at that chain's WETH9
* a compact example of the `weth9` builtin interface

### Generate it

```bash
# a full project (fetched from the registry, hash-verified, then gated)
rflow new --template community/weth-wrap-monitor

# or add the workflow to an existing project
rflow add workflow community/weth-wrap-monitor
```

Non-interactive (CI/agents):

```bash
rflow new --template community/weth-wrap-monitor --yes --output ./weth \
  --answer min_amount=100
```

### Inputs

| key                                            | type                                    | default                                     |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| `project_name`                                 | string                                  | `weth-wrap-monitor`                         |
| `network` / `chain_id` / `rpc_env` / `rpc_url` | network / chain\_id / env\_var / string | `ethereum` / `1` / `ETH_RPC` / a public RPC |
| `weth_name` / `weth_address`                   | contract / address                      | `WETH` / mainnet WETH9                      |
| `min_amount`                                   | token\_amount                           | `100`                                       |
| `channel`                                      | string                                  | `ops`                                       |
| `tg_bot_token_env` / `tg_chat_id_env`          | env\_var                                | `TG_BOT_TOKEN` / `TG_CHAT_ID`               |

WETH is 18 decimals — the threshold and formatting use `18` directly.

### Required env vars

`DATABASE_URL`, the RPC env var (default `ETH_RPC`), and the telegram
credentials (default `TG_BOT_TOKEN` / `TG_CHAT_ID`) — all in the generated
`.env.example`.

### Safety notes

Monitor-only: no `signer:` and no `relayers:`, so the relayer engine never
boots. The install records the registry, commit and per-file sha256s in
`.rflow/template-lock.yaml`, and both workflows end in
`on_failure: dead_letter`.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env
rflow validate
rflow start
```

### Common modifications

* change `weth_address` for L2s / other chains' canonical WETH
* drop one workflow if you only care about wraps (or unwraps)
* lower `min_amount` to watch all sizeable flow


## Workflow error pager

**Template:** `workflow-error-pager` · **category:** monitoring · **risk:** `monitor_only`

The catch-all pager for an unattended rflow deployment: a
[`workflow_error` meta-trigger](/operations/unattended-ops#the-workflow_error-meta-trigger)
watching `"*"` — every other workflow in the project — and paging a pagerduty
or telegram channel the moment a run settles `dead_letter` (and, by default,
`failed` too). No signer, no relayer, no transactions.

### When to use it

* the first thing to add to ANY production rflow project — failures should
  page you, not wait in `rflow dead-letter ls`
* route run failures to the on-call rotation (pagerduty) or an ops chat
  (telegram)
* alongside [`liveness:`](/operations/unattended-ops#liveness--alert-when-a-workflow-goes-silent),
  which covers the silence failures this trigger cannot see

### Generate it

```bash
# usually: add the pager to the project it should watch
rflow add workflow workflow-error-pager

# or as a standalone starting project
rflow new --template workflow-error-pager
```

Non-interactive (CI/agents):

```bash
rflow new --template workflow-error-pager --yes --output ./pager \
  --answer pager=telegram --answer page_on_failed=false
```

### The generated YAML

```yaml
# recipe: partial
workflows:
  workflow-error-pager:
    trigger:
      workflow_error:
        workflows: "*"
        on: [dead_letter, failed]
    steps:
      - id: page
        notify:
          channel: pager
          message: "rflow failure: ${{ trigger.failed.workflow }} run ${{ trigger.failed.run_id }} settled ${{ trigger.failed.status }} at step ${{ trigger.failed.step_id }} (attempt ${{ trigger.failed.attempt }}) - ${{ trigger.failed.error.kind }}: ${{ trigger.failed.error.message }}"
    on_failure: drop
```

### Inputs

| key              | type                               | default                                                     |
| ---------------- | ---------------------------------- | ----------------------------------------------------------- |
| `project_name`   | string                             | `workflow-error-pager`                                      |
| `channel`        | string                             | `pager`                                                     |
| `pager`          | choice (`pagerduty` \| `telegram`) | `pagerduty`                                                 |
| `page_on_failed` | bool                               | `true` — also fire for `on_failure: drop \| halt` workflows |

### Required env vars

`DATABASE_URL`, plus **one** credential set depending on the `pager` answer:
`PAGERDUTY_ROUTING_KEY` (an Events API v2 integration key) *or*
`TG_BOT_TOKEN`/`TG_CHAT_ID`. The generated `.env.example` contains exactly
the set you chose.

### Safety notes

* **Recursion-guarded by rflow itself**: a workflow whose trigger is
  `workflow_error` never fires other watchers — a broken pager logs loudly
  instead of starting an alert storm. That is also why the template ends in
  `on_failure: drop`, not `dead_letter`: the pager must never park runs a
  human has to clean up.
* Watching `"*"` matches every non-watcher workflow **in the same project**,
  including ones you add later — no list to maintain.
* Replay/`rflow test` rehearsal runs never feed the trigger.

### Run it locally

```bash
docker compose up -d     # postgres on localhost:5448
# fill .env (pagerduty routing key or telegram credentials)
rflow validate
rflow start
```

To see it fire, add any workflow that dead-letters (e.g. an `http_call` to a
port nothing listens on) and trigger it — the page arrives with the failing
workflow, step, attempt and error kind. `fixtures/failed-run.json` documents
the exact `trigger.failed.*` shape the message renders against.

### Production checklist

* [ ] pagerduty: use a dedicated Events API v2 integration per rflow
  deployment, so pages carry the right service
* [ ] decide `page_on_failed`: `true` pages for `drop`/`halt` workflows too;
  `false` pages only for parked (`dead_letter`) runs that need a human
* [ ] add [`liveness:`](/operations/unattended-ops#liveness--alert-when-a-workflow-goes-silent)
  to the workflows that must never go silent — the pager only sees runs
  that FAIL, not runs that never start
* [ ] rehearse the path once: force a dead-letter, watch the page, then
  `rflow dead-letter requeue` the run

### Common modifications

* narrow the watch: `workflows: [usdc-transfer-relay, treasury-sweep]`
  instead of `"*"`
* POST to an incident webhook instead of (or before) the page: swap the
  `notify:` for an `http_call:` — the fixture shows the payload shape
* keep `on: [dead_letter]` only, and let `drop` workflows fail silently by
  design


## Community registry

The template registry has two tiers in one repo, behind one trust gate (PR
review into master):

* **builtin** — the first-party set, compiled into the binary (offline
  bootstrap; everything on the [registry page](/templates)).
* **community** — packages under
  [`templates/community/`](https://github.com/joshstevens19/rflow/tree/master/templates/community)
  at the repo root. They are **not** in the binary: the CLI discovers and
  installs them over the GitHub API, so a template merged today is
  installable by every rflow binary already in the wild.

```bash
rflow templates ls --community                    # the remote index
rflow new --template community/large-approval-alert
rflow add workflow community/large-approval-alert
```

The interactive `rflow new` picker also ends with a *"community template
(fetched from the registry)"* entry that fetches the index and lists the
community ids.

### The trust model

Distribution is **pinned, never live** — trust never attaches to a branch,
only to reviewed, hashed content:

1. **PR-reviewed.** The only way into the registry is a PR merged into
   master. A community package is reviewable by construction: manifest,
   typed inputs, YAML templates and (surface-verified) ABI files — no code,
   no hooks.
2. **SHA-pinned.** Every install resolves the branch to a COMMIT first,
   then fetches `index.json` and every package file *at that commit*
   (`raw.githubusercontent.com/<owner>/<repo>/<commit>/…`). A force-pushed
   or rewritten history cannot change what anyone installs.
3. **Hash-verified.** `index.json` pins a sha256 for EVERY file of every
   package (snapshots and READMEs included). Each downloaded byte is
   re-hashed before it is kept; a mismatch aborts the install and keeps
   nothing. Verified downloads are cached (`~/.rflow/cache`, override with
   `RFLOW_CACHE_DIR`) and **re-hashed on every use** — a tampered cache file
   is re-downloaded, never trusted. Set `GITHUB_TOKEN` to raise the API rate
   limit.
4. **Immutable versions.** CI refuses any change to a published package's
   files without a `template_version` bump — and enforces the same rules
   against the base branch, so regenerating `index.json` inside a PR cannot
   smuggle in a rewrite. Version *downgrades* fail. *Removing* an id fails:
   templates retire via `deprecated: true` in the manifest (still
   installable, labeled in `ls`/`show`, installs with a warning).
5. **The full local gate re-runs at install.** Before anything renders, the
   installing CLI runs the community doctor profile, verifies every
   declared interface surface, and prints a provenance banner (registry,
   commit, risk, author). Merged review is necessary, not sufficient — your
   own binary re-proves the package.

### Install UX

`community/<id>` is explicit; a plain id that no builtin claims also falls
back to the community index. Builtin names are **reserved** — a community
package can never shadow one. Every community install prints its
provenance before rendering:

```
community template 'large-approval-alert' v1.0.0 (risk: monitor_only)
  registry: github:joshstevens19/rflow@master
  commit:   3f2a9c…
  author:   rflow maintainers
```

#### Forks and private registries

`--registry github:owner/repo[@branch]` points the SAME mechanism at any
fork — the org-internal/private sharing story with zero extra machinery:

```bash
rflow templates ls --community --registry github:acme/rflow-templates
rflow new --template community/acme-vault-alert --registry github:acme/rflow-templates
```

Non-default registries are loudly labeled **UNTRUSTED** — nothing in them
was reviewed by the rflow maintainers — and require an explicit
confirmation (`--yes` in scripts, a prompt on a TTY).

#### Lock provenance

Community installs extend
[`.rflow/template-lock.yaml`](/templates/using-templates#the-lock-file)
with the full provenance — what was installed, from where, pinned to which
commit, hashing to what:

```yaml
templates:
  - id: large-approval-alert
    template_version: 1.0.0
    rflow_version: 0.1.0
    installed_at: "2026-08-08T12:00:00Z"
    answers:
      network: ethereum
      # …
    source: community
    registry: github:joshstevens19/rflow@master
    commit: 3f2a9c1d…
    files:
      template.yaml: 6797d64b…   # sha256 per packaged file
      rflow.yaml.tmpl: bc7c730b…
```

Builtin installs keep the exact pre-community entry shape — none of the new
keys appear.

### Declared interfaces

A template bundling an opaque ABI blob is unreviewable — and a poisoned ABI
encodes different calldata. `interfaces:` in `template.yaml` fixes that:
the manifest declares the EXACT function/event signatures the workflows
use, and whatever the ABI source yields must carry those signatures
(checked by **recomputed selectors and topic0s**) or the template fails
doctor and refuses to install.

```yaml
interfaces:
  token:
    abi:
      wellknown: erc20            # curated builtin standard - ships NO blob;
    functions: []                 # the install materializes abis/token.json
    events:
      - "Approval(address,address,uint256)"

  pool:
    abi:
      fetch:                      # resolved at install time from TYPED inputs
        address_from: pool_address   # an input of type address
        network_from: network        # an input of type network
    functions:
      - "getUserAccountData(address)"

  settlement:
    abi:
      file: settlement            # bundled abis/settlement.json - acceptable
    functions:                    # ONLY because it is machine-verified
      - "fill(bytes32,bytes,bytes)"
    events:
      - "Open(bytes32,(address,uint256))"
```

Exactly one source per interface — `wellknown:` (curated builtin standards:
erc20 and friends), `fetch:` (from typed address/network inputs, never
literals), or `file:` (a bundled blob, verified against the declaration).
`fetch:`/`file:` interfaces must declare a non-empty surface — an
unverifiable declaration is refused.

`endpoints:` declares HTTP egress the same way — a fixed `host:` or a
`host_from:` input, plus which `requires.secrets` entry travels there:

```yaml
endpoints:
  report:
    host_from: report_host
    secret: REPORT_HMAC
```

`rflow templates show <id>` prints the complete call + egress surface
before anything installs.

### Submitting a template

The process is deliberately boring, like an EIP — one directory, one PR,
one mechanical review:

```bash
# 1. scaffold a compliant skeleton (inside a checkout of the rflow repo)
rflow templates scaffold my-vault-alert

# 2. fill it in: template.yaml (author:, inputs, interfaces), rflow.yaml.tmpl,
#    README.md, answers.sample.yaml - then generate the snapshot
rflow templates snapshot my-vault-alert --dir templates/community/my-vault-alert

# 3. regenerate the index (this also runs the community doctor gate over
#    every package) and prove it is current
rflow templates index
rflow templates index --dir . --check

# 4. open the PR - CI re-runs the whole gate, one maintainer approval merges
```

The scaffolded skeleton passes the full community doctor profile the moment
its snapshot exists, so you start from green. The full checklist lives in
[`templates/community/SUBMITTING.md`](https://github.com/joshstevens19/rflow/blob/master/templates/community/SUBMITTING.md).

Note: `RFLOW_REGENERATE_TEMPLATE_SNAPSHOTS=1 cargo test -p rflow_core
regenerate_template_snapshots` only regenerates the EMBEDDED first-party
snapshots — community packages regenerate with `rflow templates snapshot`.

### The community profile

CI (and every install) enforces the first-party
[doctor checks](/templates/using-templates#verify-rflow-templates-doctor)
PLUS the community rules — all mechanical, none advisory:

| rule                                                                     | why                                                                                                           |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `author:` is mandatory                                                   | an EIP-style process puts a name on every proposal                                                            |
| no `command:` steps, anywhere in the step tree                           | a community template may not ship arbitrary execution                                                         |
| no literal addresses in `prepares_tx` / `money_moving` templates         | destinations are typed inputs the installer answers (the zero address stays allowed as a placeholder)         |
| every bundled ABI blob is covered by a `file:` interface                 | the blob is machine-verified against the declared signatures — better, ship no blob (`wellknown:` / `fetch:`) |
| typed inputs for every installer choice; defaults validate               | answers are type-checked before rendering                                                                     |
| `outputs.files` equals exactly what the package produces                 | materialized interface ABIs (`abis/<name>.json`) count as produced                                            |
| sample render passes `rflow validate` and matches the committed snapshot | byte for byte                                                                                                 |
| a docs page exists for `docs.page`                                       | checked in-repo by CI (skipped by installing binaries)                                                        |

Deprecated templates (`deprecated: true`) stay in the catalog and stay
installable — the index is immutable — but are labeled in `ls`/`show` and
install with a warning.


## Creating templates

Templates are **data, not code**: a package is a manifest plus files. There
are no generation hooks and no template-supplied code execution — rendering is
plain substitution, and every install path ends in `rflow validate`. Adding a
template to the registry is adding a directory; no code or index edit is
required (the registry discovers packages at build time).

> This page covers **first-party embedded** templates, which live in
> `crates/core/templates/` and compile into the binary. To share a template
> with everyone WITHOUT waiting for a release, submit it to the
> [community registry](/templates/community-registry) instead —
> `rflow templates scaffold <id>` writes the skeleton, and a merged PR is
> installable immediately by every existing binary.

### Package layout

```text
crates/core/templates/<id>/
  template.yaml          # the manifest — id MUST equal the directory name
  README.md              # for humans browsing the repo (not generated)
  answers.sample.yaml    # doctor/snapshot answers (not generated)
  rflow.yaml.tmpl        # rendered -> rflow.yaml
  env.example.tmpl       # rendered -> .env.example
  gitignore              # copied   -> .gitignore
  docker-compose.yml     # copied   -> docker-compose.yml
  abis/<name>.json       # copied verbatim (one per requires.abis entry)
  scripts/*.js           # copied verbatim (command-step templates)
  fixtures/*.json        # copied verbatim (rflow test / rflow replay inputs)
  tests/expected-rflow.yaml  # committed snapshot (not generated)
```

Everything except `template.yaml`, `README.md`, `answers.sample.yaml` and
`tests/` is an **output**: `*.tmpl` files render, everything else copies
byte-for-byte. `outputs.files` in the manifest must list exactly the generated
paths (post-rename: `rflow.yaml`, `.env.example`, `.gitignore`, …) — doctor
fails on any mismatch.

### The manifest

```yaml
id: my-template            # = directory name
title: My Template
category: monitoring       # treasury | monitoring | keeper | intents | bridge-ops
                           # | governance | security | relayers | offchain | examples
rflow_min_version: "0.1.0"
template_version: "1.0.0"
risk: monitor_only         # monitor_only | prepares_tx | money_moving | admin | experimental
summary: "One line for the ls table."
aliases: []                # optional extra ids that resolve here

inputs:                    # declaration order = prompt order
  project_name:
    type: string
    prompt: "Project name"
    default: my-template
    pattern: "^[a-z0-9][a-z0-9-]*$"
  token_address:
    type: address
    prompt: "ERC20 token address"
    required: true

requires:
  database: true
  signer: false
  relayers: []             # names the template's yaml declares
  abis: []                 # names matching abis/<name>.json
  secrets:
    - name: TG_BOT_TOKEN
      optional: true

outputs:
  files: [rflow.yaml, .env.example, .gitignore, docker-compose.yml]

safety:                    # honest metadata shown by `templates show`
  requires_simulation: false
  requires_approval: false

docs:
  page: /use-cases/my-template   # must exist under documentation/docs/pages
  example: examples/my-example   # optional
```

#### Input types

`string`, `bool`, `int`, `decimal`, `duration`, `cron`, `address` (EIP-55
checked on mixed case), `tx_hash`, `network`, `chain_id`, `contract`,
`abi_path`, `token_amount`, `choice` (with `options:`), `list`, `secret_name`,
`env_var` — plus per-input `required`, `default`, `pattern` and `prompt`.
Validation runs before rendering, and the rendered project is validated again
through normal `rflow validate`.

### Rendering rules

Templates render with [minijinja](https://docs.rs/minijinja) configured with
**custom delimiters** so rflow's own syntax passes through untouched:

| syntax                       | meaning                                                         |
| ---------------------------- | --------------------------------------------------------------- |
| `[[ input_key ]]`            | template placeholder (strict — an unknown key fails the render) |
| `[% if ... %] … [% endif %]` | template logic (e.g. a `choice` switching a channel block)      |
| `[# ... #]`                  | template comment                                                |
| `${{ ... }}`                 | an **rflow expression** — written literally, passes through     |
| `${VAR}`                     | an **env placeholder** — written literally, passes through      |

Gotcha: minijinja's whitespace trim markers (`[%-` / `-%]`) strip the *next
line's indentation* too, which corrupts YAML. Put conditional tags **inline at
the end of a line** instead (see `workflow-error-pager`'s templates for the
pattern).

Money templates must render the full safety rails **into the YAML**:
simulation + `assert_sim`, a gas cap, `recheck:`, trigger `confirmations` +
`run_on: confirmed`, `wait_for: confirmed`, `on_failure: dead_letter`, a
concurrency group — and an `approval:` gate for treasury/admin flows.

### The recipe

1. `mkdir crates/core/templates/<id>/` and fill in the layout above (copy a
   seed like `large-transfer-alert` for the shapes). Every key in
   `answers.sample.yaml` must be a declared input.

2. Generate the snapshot, then review and commit it:

   ```bash
   RFLOW_REGENERATE_TEMPLATE_SNAPSHOTS=1 \
     cargo test -p rflow_core regenerate_template_snapshots
   ```

3. Add a one-line snapshot test to your group file
   (`crates/core/src/template_registry/tests_group_<x>.rs`):

   ```rust
   #[test]
   fn my_template_snapshot() { super::assert_template_snapshot("my-template"); }
   ```

4. Write the docs page at `documentation/docs/pages/use-cases/<id>.mdx`
   (matching `docs.page`) and link it from `/use-cases`. The page shape:
   what it does, when to use it, the generated YAML, inputs, env vars,
   safety notes, local run, production checklist, common modifications.

5. Verify. `include_dir` does **not** trigger rebuilds when only template
   files change — touch the registry first:

   ```bash
   touch crates/core/src/template_registry/registry.rs
   cargo test -p rflow_core template_registry
   cargo run --bin rflow -- templates doctor <id>
   cargo run --bin rflow -- new --template <id> --yes --output /tmp/x
   cargo run --bin rflow -- validate -p /tmp/x
   ```

Definition of done: doctor passes (which includes the sample-answers
render + validate, the outputs check and the snapshot), and the docs page
exists.


## Templates

rflow ships a first-party **template registry**: 27 productized recipes that
turn "I want to watch a Safe / relay deposits / page on dead-letters" into a
validated, production-shaped project in one command. A template is not a
snippet — it knows rflow semantics end to end: typed inputs, networks,
contracts, packaged ABIs, relayers, notification channels, secrets, safety
defaults, replay fixtures, a docs recipe and snapshot tests.

```bash
rflow templates ls                    # browse (filter: --category, --risk, --json)
rflow new --template safe-monitor     # scaffold a complete project
rflow add workflow workflow-error-pager   # compose into an EXISTING rflow.yaml
```

See [Using templates](/templates/using-templates) for the full command
walkthrough, [Creating templates](/templates/creating-templates) to add your
own, and the [use-case recipes](/use-cases) for one page per template. The
runnable walkthrough lives at
[`examples/template-gallery`](https://github.com/joshstevens19/rflow/tree/master/examples/template-gallery)
(`make run-template-gallery` from the repo root).

Beyond the builtin set there is a **[community registry](/templates/community-registry)**:
templates submitted by PR into the rflow repo, fetched SHA-pinned and
hash-verified at install time (`rflow templates ls --community`,
`rflow new --template community/<id>`) — merged today, installable today by
every existing binary.

### The registry

| id                                                                    | category   | risk           | summary                                                                                                                                               |
| --------------------------------------------------------------------- | ---------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`aave-health-guardian`](/use-cases/aave-health-guardian)             | keeper     | `money_moving` | Poll an Aave v3 position's health factor and park an approval-gated repay when it drops                                                               |
| [`bridge-message-watch`](/use-cases/bridge-message-watch)             | bridge-ops | `monitor_only` | Cross-reference a bridge's MessageSent/MessageReceived by nonce and alert on missed delivery                                                          |
| [`chainlink-deviation-alert`](/use-cases/chainlink-deviation-alert)   | monitoring | `monitor_only` | Cron-compare two Chainlink feeds and alert when they disagree beyond a basis-point threshold                                                          |
| [`chainlink-oracle-staleness`](/use-cases/chainlink-oracle-staleness) | monitoring | `monitor_only` | Poll a Chainlink feed's `latestRoundData` and alert when `updatedAt` goes stale                                                                       |
| [`command-decision`](/use-cases/command-decision)                     | examples   | `monitor_only` | Cron reads a token supply on-chain, a project-owned script decides a severity, rflow reports it                                                       |
| [`command-trade-prep`](/use-cases/command-trade-prep)                 | relayers   | `money_moving` | A deposit event fires a project-owned quote script; rflow signs, simulates, rechecks and sends the trade                                              |
| [`cron-http-report`](/use-cases/cron-http-report)                     | offchain   | `monitor_only` | A cron POSTs an HMAC-signed JSON heartbeat report to an HTTP endpoint                                                                                 |
| [`erc4626-vault-monitor`](/use-cases/erc4626-vault-monitor)           | monitoring | `monitor_only` | Alert on large ERC-4626 deposits/withdrawals and when the share price drops below a floor                                                             |
| [`erc721-floor-sweep-watch`](/use-cases/erc721-floor-sweep-watch)     | monitoring | `monitor_only` | Index an ERC-721 collection's Transfers and alert when one wallet sweeps many in a window                                                             |
| [`erc7683-solver`](/use-cases/erc7683-solver)                         | intents    | `money_moving` | Fill ERC-7683 intents: Open event, profitability quote, race check, fill                                                                              |
| [`large-transfer-alert`](/use-cases/large-transfer-alert)             | monitoring | `monitor_only` | Alert a notification channel when an ERC20 transfer crosses a threshold                                                                               |
| [`liquidation-keeper`](/use-cases/liquidation-keeper)                 | keeper     | `money_moving` | Poll a borrower's health factor and fire a simulated, gas-capped liquidation                                                                          |
| [`native-spend-report`](/use-cases/native-spend-report)               | treasury   | `monitor_only` | Cron-aggregate the journal's send history into an HMAC-signed HTTP + chat spend report                                                                |
| [`price-alert-stream`](/use-cases/price-alert-stream)                 | monitoring | `monitor_only` | Subscribe to a public price WebSocket feed, filter by symbol + threshold, and notify                                                                  |
| [`proxy-upgrade-alert`](/use-cases/proxy-upgrade-alert)               | security   | `monitor_only` | Alert when an ERC1967 proxy emits Upgraded — with the old and new implementation                                                                      |
| [`relayer-low-balance-alert`](/use-cases/relayer-low-balance-alert)   | relayers   | `monitor_only` | Poll a relayer wallet's native balance and alert once when it crosses under a floor                                                                   |
| [`safe-monitor`](/use-cases/safe-monitor)                             | security   | `monitor_only` | Watch a Safe for owner/threshold changes and successful executions — notify                                                                           |
| [`safe-owner-change-alert`](/use-cases/safe-owner-change-alert)       | security   | `monitor_only` | Watch a Safe for AddedOwner/RemovedOwner/ChangedThreshold and report the new threshold                                                                |
| [`security-advisory-watch`](/use-cases/security-advisory-watch)       | security   | `monitor_only` | Poll an RSS/Atom security feed (trigger.web) and page on every NEW matching advisory — deduped by link                                                |
| [`solver-inventory-rebalance`](/use-cases/solver-inventory-rebalance) | intents    | `money_moving` | Poll a solver wallet's ERC20 inventory and top it up from a funding wallet behind approval                                                            |
| [`solver-pnl-report`](/use-cases/solver-pnl-report)                   | intents    | `monitor_only` | Cron-summarize a solver's fill workflow from the journal: filled, skipped/raced, failed, native spend                                                 |
| [`timelock-monitor`](/use-cases/timelock-monitor)                     | governance | `monitor_only` | Watch an OpenZeppelin TimelockController for scheduled/executed/cancelled operations                                                                  |
| [`token-deposit-relay`](/use-cases/token-deposit-relay)               | relayers   | `money_moving` | ERC20 deposits into a watched address trigger a gated, relayed payout                                                                                 |
| [`treasury-sweep-approval`](/use-cases/treasury-sweep-approval)       | treasury   | `money_moving` | Cron reads a hot wallet ERC20 balance and parks a sweep behind approval                                                                               |
| [`uniswap-v3-lp-monitor`](/use-cases/uniswap-v3-lp-monitor)           | monitoring | `monitor_only` | Alert when a Uniswap v3 pool's price tick leaves an LP range — on Swap events and a slot0 poll                                                        |
| [`webhook-idempotent-handler`](/use-cases/webhook-idempotent-handler) | offchain   | `prepares_tx`  | An HMAC-authenticated webhook with a native idempotency\_key feeds a command step that validates, dedupe-keys and prepares a transfer; rflow notifies |
| [`workflow-error-pager`](/use-cases/workflow-error-pager)             | monitoring | `monitor_only` | Page pagerduty or telegram when ANY workflow's run dead-letters or fails                                                                              |

### Risk labels

Every template carries an honest risk label — filter with
`rflow templates ls --risk <label>`:

* **`monitor_only`** — no signer, no relayer, no transactions. The generated
  project physically cannot move money.
* **`prepares_tx`** — creates transaction data (calldata, dedupe keys) but
  never broadcasts; there is no signer in the project.
* **`money_moving`** — sends transactions through the embedded relayer.
* **`admin`** — contract ownership / proxy / pause / timelock actions.
* **`experimental`** — useful, but not a recommended production starting
  point.

(No bundled template is currently `admin` or `experimental`.)

### Safety defaults on money templates

Every `money_moving` template renders the full set of rails — they are in the
generated YAML, not implied by the runtime:

* pre-broadcast **simulation** with `assert_sim: ["${{ sim.ok }}"]` and
  `gas.limit_from_simulation`
* a **gas price/cost cap** (`gas.max_price` / `max_cost`)
* a **`recheck:`** re-evaluated immediately before broadcast wherever a
  time-varying guard exists (`erc7683-solver`'s fill deadline,
  `command-trade-prep`'s quote freshness) — flows whose only broadcast-time
  guard is the fresh simulation ship none rather than a recheck that only
  re-tests journaled constants
* trigger-level **`confirmations` + `run_on: confirmed`** — a reorged deposit
  never even creates a run
* `wait_for: confirmed` on the send and `on_failure: dead_letter` on the
  workflow
* a **concurrency group** (`queue` for event relays, `skip` for keepers)
* an **`approval:` gate** on treasury/admin flows
  (`treasury-sweep-approval` parks behind a human `rflow approve`)

### What every template package guarantees

`rflow templates doctor --all` enforces, for each of the 27 packages: the
manifest parses strictly, the declared output files match the packaged files,
required ABIs are packaged, all inputs are well-formed, the **sample answers
render a project that passes `rflow validate`**, the committed snapshot
matches, and the docs page exists. Installs are recorded in
[`.rflow/template-lock.yaml`](/templates/using-templates#the-lock-file).


## Using templates

Three commands cover the whole lifecycle: **browse** the registry, **scaffold**
a new project, **compose** a template into an existing one.

### Browse: `rflow templates`

```bash
rflow templates ls                          # the table: id, category, risk, summary
rflow templates ls --category treasury      # filter by category
rflow templates ls --risk money_moving      # filter by risk label
rflow templates ls --json                   # machine-readable
rflow templates search oracle               # keyword search over id/title/summary
rflow templates show token-deposit-relay    # human detail (files, inputs, requires, safety)
rflow templates inspect token-deposit-relay # the raw manifest as JSON (agents/tooling)
rflow templates doctor token-deposit-relay  # prove the bundled package is shippable
```

`show` answers "what happens if I install this" **before** you install it:
the generated files, every typed input with its default, whether it needs a
signer/relayers/ABIs/secrets, the safety profile (confirmations, simulation,
recheck, approval) and the docs page.

### Scaffold: `rflow new --template <id>`

```bash
# interactive: a template picker, then one typed prompt per input
rflow new

# direct: prompts only for this template's inputs
rflow new --template treasury-sweep-approval

# non-interactive (CI/agents): defaults fill everything not answered
rflow new --template large-transfer-alert --yes --output ./alerts \
  --answer network=base --answer chain_id=8453 --answer min_amount=250000

# or drive it from a file of `key: value` scalars
rflow new --template safe-monitor --yes --output ./safe --answers-file answers.yaml
```

Answer precedence is `--answers-file` \< `--answer key=value` \< interactive
prompts; manifest defaults fill whatever remains. Every answer is
**type-checked before anything is written** — addresses are validated (EIP-55
checksums honored on mixed-case), crons parsed, durations/amounts/chain-ids
checked, `choice` inputs constrained to their options, patterns enforced. A
bad answer is a clear error naming the key; nothing half-scaffolds.

A successful scaffold writes the files the manifest declares (`rflow.yaml`,
`.env.example`, `.gitignore`, `docker-compose.yml`, ABIs, fixtures, scripts),
generates `.env` from `.env.example`, runs `rflow validate`, and prints the
next commands. Existing files are **never overwritten silently** — an existing
`rflow.yaml` refuses the scaffold, an existing `.env` is left untouched.

Templates that require a signer (`money_moving`) generate a **DEV-ONLY
mnemonic into `.env`** (never into `.env.example`) so the project boots
locally — swap in a real signer before production.

Legacy scaffold ids keep working: `transfer-alert`, `cron-report` and
`treasury-approval` are manifest aliases; `liquidation-keeper` resolves to the
registry package of the same id; `webhook-relay` and `blank` still use the
pre-registry renderer.

#### The lock file

Every install appends to `.rflow/template-lock.yaml`:

```yaml
templates:
  - id: large-transfer-alert
    template_version: "1.0.0"
    rflow_version: "0.1.0"
    installed_at: "2026-08-03T12:00:00Z"
    answers:
      network: base
      min_amount: "250000"
```

It is the audit trail of what was generated from what — and the input a
future `rflow templates update` will diff against. Answers of type
`secret_name` are excluded on purpose.

### Compose: `rflow add workflow <template-id>`

```bash
rflow add workflow chainlink-oracle-staleness            # into the current project
rflow add -p ./alerts workflow workflow-error-pager --yes
rflow add workflow large-transfer-alert --name usdt-alert --answer token_address=0x...
rflow add workflow native-spend-report --dry-run         # print the plan, write nothing
```

`add workflow` renders the template with your answers, then **structurally
merges** its contracts, relayers, constants, secrets, lists, notification
channels and workflow(s) into the existing `rflow.yaml` — comments, ordering
and formatting preserved byte-for-byte outside the appended entries. Packaged
files (ABIs, fixtures, scripts) are copied alongside; identical files are
skipped, differing ones refuse.

Inputs the project already satisfies are not re-asked: `project_name` prefills
from the config, `network`/`chain_id` from the project's single network (a
multi-network project gets a picker). `networks:` and `signer:` are **never
merged** — an existing project owns its chains and keys; a template that needs
a missing network or signer is refused by validation with the exact error.

Collision rules, per entity:

| situation                                                     | behavior                            |
| ------------------------------------------------------------- | ----------------------------------- |
| identical entry already exists                                | reused silently (reported as `=`)   |
| same contract name, same ABI, template's addresses ⊆ existing | reused with a warning               |
| same name, different value                                    | hard error — rename one side        |
| workflow name taken                                           | error demanding `--name <new-name>` |

Multi-workflow templates (`safe-monitor` splices 4 workflows,
`timelock-monitor` 3, `bridge-message-watch` 2) add **every** workflow they
declare, in authored order; `--name` only applies to single-workflow
templates.

Before writing, the merged config is validated in memory: any change that
would **introduce** a validation error is refused with the file untouched
(errors that a pending file copy resolves — the ABI about to be written — are
accounted for). A successful add appends to the lock file, prints which
`${VAR}` env vars the new entries need, and ends with `rflow validate`.

### Verify: `rflow templates doctor`

```bash
rflow templates doctor <id>     # one template
rflow templates doctor --all    # the whole registry (CI gate)
```

Checks per template: strict manifest parse, `rflow_min_version` compatibility,
declared outputs exactly match the packaged files, required ABIs packaged,
inputs well-formed, **sample answers render a project that passes
`rflow validate`**, the committed snapshot matches, and the docs page exists
(skipped outside the repo). Exit 1 on any failure.


## Doctor & explain — pre-deploy diagnosis and PR review

Two commands cover the "is this safe to boot?" question from both ends:

* [`rflow doctor`](#rflow-doctor--the-operational-suite) — **live** diagnosis:
  every check that can be verified against the real world (DB, RPCs, relayer
  balances, channels) plus static posture guidance, each with a severity and a
  fix hint. Safe to gate CI and deploys on.
* [`rflow explain`](#rflow-explain--the-plain-english-narrative) — **static**
  narrative: what a workflow does, what sends money, and what stands between a
  trigger firing and a transaction broadcasting. Built for PR review.

Run `doctor` before every deployment; paste `explain --risk` into every PR that
touches a money workflow.

### `rflow doctor` — the operational suite

```bash
rflow doctor [--path <dir>] [--profile <name>] [--deep] [--json]
```

The quick readiness table (Docker, Foundry, Postgres, Node, the `rflow.yaml`
validate summary — see [Scaffolding](/getting-started/scaffolding#rflow-doctor--local-readiness))
prints first. When a project is present the **deep suite** follows
automatically (`--deep` only makes it explicit; outside a project only the tool
checks run). With `--profile`, doctor diagnoses the **merged** view — the exact
config `rflow start --profile <name>` would boot.

```
deep checks
 check                                  | severity | status | detail
 config.valid                           | error    | pass   | valid - 1 workflow(s), 1 warning(s)
 contract.Token                         | error    | pass   | abi parses (2 event(s), 9 function(s)); 1 static address(es) checksum-valid
 db.connect                             | error    | pass   | connected
 db.schema                              | info     | pass   | rflow schema present (migrations applied)
 relayer.treasury.mapping.ethereum      | warning  | FAIL   | no rflow.relayers row for chain 1
 rpc.ethereum                           | error    | pass   | chain id 1 matches
 signer.raw                             | warning  | pass   | mnemonic resolves (24 words) - dev-only; use a managed signer in production
 approval.treasury-sweep-approval.sweep | warning  | pass   | gates the broadcast via cli, timeout 1h -> fail
 coverage.treasury-sweep-approval       | info     | FAIL   | money workflow without: rate_limit, circuit_breaker, permissions.max_value_per_tx

How to fix:
  - relayer.treasury.mapping.ethereum [warning]: `rflow start` creates the wallet on first boot (or `rflow relayers sync`)
  - coverage.treasury-sweep-approval [info]: each is optional - but they are the blast-radius caps when something upstream goes wrong

doctor: ok - 7 check(s) passed, 1 warning(s), 0 advice, 1 info (warnings/advice never block)
```

#### The check catalogue

Check ids are **stable** — key CI logic off them, not off titles or details.

| check id                             | severity         | what it verifies                                                                                                                                                                                                                        |
| ------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config.valid`                       | error            | the config (post-profile-merge) passes strict validation                                                                                                                                                                                |
| `config.profile.<name>`              | error / warning  | a `profiles.<name>` overlay applies cleanly and the merged config validates — **error** for the `--profile` you selected, warning for other declared profiles checked in passing                                                        |
| `contract.<name>`                    | error            | the ABI file parses; every static address is EIP-55 checksum-valid                                                                                                                                                                      |
| `db.connect`                         | error            | Postgres reachable via `config.db_connection` (bounded `SELECT 1`)                                                                                                                                                                      |
| `db.schema`                          | info             | the `rflow` schema and its migration sentinel exist (a fresh project passes this only after the first `rflow start`)                                                                                                                    |
| `rpc.<network>[.N]`                  | error            | every RPC url answers `eth_chainId` and it **matches the declared `chain_id`** — a mismatch means every address/nonce assumption is wrong                                                                                               |
| `rpc.<network>.finalized`            | advice           | the node answers a `finalized`-tag block query — probed only when a workflow actually uses `finalized` (event `confirmations: finalized` or send `wait_for: finalized`)                                                                 |
| `rpc.<network>.archive`              | advice           | best-effort archive probe (`eth_getBalance` at block `0x1`) — probed only when a workflow backfills history; passing it is *not* proof of full archive depth                                                                            |
| `relayer.<name>.mapping.<network>`   | warning          | an `rflow.relayers` row exists for the chain (`rflow start` creates the wallet on first boot)                                                                                                                                           |
| `relayer.<name>.import`              | warning          | a declared `import: { id }` has been adopted (a mapping row exists — the boot derived-address check passed); [`rflow relayers verify-imports`](/config/relayers#importing-existing-rrelayer-relayers) re-checks against the live signer |
| `relayer.<name>.balance.<network>`   | warning          | the relayer's native balance is above 0.01 ether — below that it likely cannot pay for gas                                                                                                                                              |
| `relayer.<name>.funding.<network>`   | warning          | the balance covers the [funding-plan estimate](/config/relayers#funding-operations) for the money workflows targeting the relayer — only checked when a money workflow targets it and the balance/gas price could be read               |
| `signer.raw` / `signer.private_keys` | warning          | the mnemonic / key env vars actually resolve (raw mnemonics also get a "dev-only" nudge)                                                                                                                                                |
| `signer.<cloud-provider>`            | info             | **config-shape only** for `aws_kms`, `aws_secret_manager`, `gcp_secret_manager`, `privy`, `turnkey`, `pkcs11`, `fireblocks` — no side-effect-free probe exists, so `rflow start` is what verifies them                                  |
| `channel.<name>`                     | warning          | delivery probe per sender: Telegram `getMe`, Slack/Discord webhook-host TCP, PagerDuty/Opsgenie/Twilio API reachability                                                                                                                 |
| `command.<workflow>.<step>`          | error            | every `command:` step's executable resolves (covers `steps`, `on_reorg` and `finally`)                                                                                                                                                  |
| `webhook.<workflow>`                 | warning / advice | webhook auth posture — **no auth on a workflow that queues transactions is a warning** (anyone who reaches the port can fire it); no auth on a monitor-only workflow is advice                                                          |
| `approval.<workflow>.<step>`         | warning          | approval-gate posture — `on_timeout: proceed` fails the check because an *undecided* approval broadcasts once the timeout elapses (covers `steps` and `finally`; validation rejects an `approval` in `on_reorg`)                        |
| `reorg.<workflow>`                   | advice           | head-fired triggers feeding sends / ignored confirmations (validation's send-safety warnings, grouped per workflow)                                                                                                                     |
| `history.<workflow>`                 | advice           | `start_block: earliest` with no bounded `end_block` — the trigger backfills *every* historical event before tailing live                                                                                                                |
| `cursor.<workflow>.<network>`        | warning          | a persisted trigger cursor more than 1,000 blocks behind the chain head — a long (re)backfill or a stalled indexer                                                                                                                      |
| `coverage.<workflow>`                | info             | a money-moving workflow lacking any of `rate_limit`, `circuit_breaker`, `permissions.max_value_per_tx` — optional, but they are the blast-radius caps                                                                                   |

#### Severities and the exit rule

* **error** — broken as configured; boot would misbehave. *The only severity
  that gates:* `rflow doctor` exits non-zero **iff an error-severity check
  fails**.
* **warning** — operationally risky (unfunded relayer, unauthenticated money
  webhook, `on_timeout: proceed`), never blocks.
* **advice** — posture guidance (reorg exposure, backfill volume, missing
  `finalized` support), never blocks.
* **info** — context worth knowing (schema not yet migrated, coverage notes),
  never blocks.

Skipped checks (e.g. a balance fetch against an unreachable node) report as
`skipped`, never as failures.

#### Gating CI and deploys

`--json` prints exactly one machine-readable object on stdout (logs go to
stderr), with the same exit rule:

```json
{
  "version": 1,
  "quick":   [ { "name": "docker", "status": "ok", "detail": "...", "hint": null } ],
  "checks":  [ { "id": "rpc.ethereum", "title": "rpc ethereum",
                 "severity": "error", "status": "pass",
                 "detail": "chain id 1 matches", "hint": null } ],
  "summary": { "passed": 7, "failed": 2, "skipped": 0,
               "errors": 0, "warnings": 1, "advice": 0, "info": 1 },
  "ok": true
}
```

`ok` is `true` unless an error-severity check failed. The shape is versioned
(`version: 1`) and pinned by a golden test. A GitHub Actions gate:

```yaml
- name: doctor gate
  run: |
    rflow doctor --path ./ops --profile prod --json > doctor.json
    jq '.summary' doctor.json          # visibility in the job log

# optional stricter policy: also refuse warnings
- name: no-warnings policy
  run: jq -e '.summary.warnings == 0' doctor.json
```

The first step fails on its own exit code when an error-severity check fails —
no parsing required. Key any custom policy off `summary` counts or stable
check `id`s.

`rflow validate --preflight` runs the connectivity subset of the same checks
(same functions, no duplicated logic) but keeps its stricter historical rule:
**any** failed check fails preflight, regardless of severity.

### `rflow explain` — the plain-English narrative

```bash
rflow explain [<workflow>] [--risk] [--json] [--path <dir>] [--profile <name>]
```

Fully **static** — no network, no database. It reads `rflow.yaml` (the raw
view, so `${VAR}` references stay visible and no secret values are ever
printed) and narrates it. When the raw view cannot parse (an env placeholder
in a numeric field like `chain_id: ${CHAIN_ID}`), explain substitutes the env
values to parse and then restores every string field to its `${VAR}` form
before rendering — resolved secrets still never print. With no argument, one
summary block per workflow:

```
workflow 'treasury-sweep-approval' [money_moving]
  trigger: fires on cron schedule '0 * * * *'
  steps: balance (read) -> sweep (send_transaction)
```

The risk label is the [template-registry vocabulary](/templates):
`monitor_only` (no sends), `prepares_tx` (a `command:` step with tx-shaped
input keys — a heuristic), `money_moving` (any `send_transaction`).

With a workflow name, the full breakdown: **TRIGGER** (kind, schedule/event,
conditions, confirmations), **STEPS** (in order, with `if:` conditions and
dependencies), **WHAT SENDS MONEY**, **WHAT BLOCKS MONEY** (simulation,
`assert_sim`, `recheck`, `valid_for`, approval gates, gas caps,
permissions/budgets, rate limit, circuit breaker, concurrency), **ON FAILURE**,
**ON REORG**, **REPLAY / DRY-RUN** (sends stop pre-broadcast; waits settle
unless `--with-waits`) and **EXTERNAL SYSTEMS** (HTTP hosts, channels, local
commands).

#### `--risk` — the PR-review view

`--risk` prints only the money sections plus a reviewer checklist:

```
REVIEWER CHECKLIST
  [x] pre-flight simulation on every send
  [x] simulation assertions (assert_sim)
  [x] recheck immediately before broadcast
  [x] human approval gate
  [ ] send expiry (valid_for)
  [x] gas price / cost caps
  [ ] per-tx spend cap (permissions.max_value_per_tx)
  [ ] relayer allowlist (permissions.relayers)
  [ ] rate limit
  [ ] circuit breaker
  [ ] reorg compensation steps (on_reorg)
  verdict: 5 of 11 reviewer safeguards configured
```

That is deliberately enough context to approve or reject a production change
without opening the YAML. A lightweight review pattern: require
`rflow explain <workflow> --risk` output in the PR description for any diff
touching a workflow with sends, and treat a *decreasing* verdict count as a
question to answer in review. `--json` emits the same data structured (and
deterministic) if you want to diff it mechanically between branches.

#### Honesty note

Every `explain` render ends with the same footer, and it means it:

> explain describes the CONFIGURATION, not runtime guarantees — it is not
> formal verification and not a security audit.

`explain` tells you what rflow was *asked* to do. Whether the RPC lies, the
contract behaves, or the approval channel pages the right human is exactly what
[`rflow doctor`](#rflow-doctor--the-operational-suite), staging replays
([Backtesting](/backtesting)) and [unattended-ops alerting](/operations/unattended-ops)
are for.


## History explorer — what ran, why, what it touched

rflow already journals **every** run and step (see
[reliability](/reliability)). The history explorer turns that durable journal
into an operational surface that answers the questions logs can't: *which
workflows ran in the last hour, which runs sent transactions and what was the
final status, what is parked right now, who approved a send, what changed
between a good run and a bad one, and can I export a redacted audit trail?*

It ships as **three surfaces over one query layer**, so the CLI, the API and the
UI never diverge and every one of them is secret-redacted by default:

* an **embedded web UI** at `GET /` — the run-trace viewer evolved into a full
  history explorer (workflows overview, runs, run detail timeline, transactions,
  approvals, waiting, failures, reorgs, replay/test sessions),
* a **read-only JSON API** under `GET /api/history/*` — cursor-paginated, stable
  shapes, auth-gated,
* a **CLI** — [`rflow history`](/cli#rflow-history) and
  [`rflow runs diff` / `rflow runs timeline`](/cli#rflow-runs), useful over SSH
  with `--json` for automation.

:::info
The explorer is **read-only** and, like the rest of rflow's port, a
localhost / private-network operator tool by default. It never edits workflows,
never exposes raw secrets, and is not a hosted multi-tenant dashboard. Turn on
[auth](#authentication) before exposing it inside private infrastructure; never
put it on the public internet.
:::

### The shared query layer

There is exactly **one** read-optimised query module —
`rflow_core::history::HistoryReader` — and both the CLI and the API call it. It
gives three properties to every result:

1. **Keyset (cursor) pagination**, not just `limit`. Pages key on
   `(created_at, id)` newest-first and hand back an opaque `cursor` plus
   `has_more`; passing that cursor to the next request continues exactly where
   the last one stopped — a row is never skipped or returned twice, even as new
   runs land between pages.
2. **Secret redaction by default.** Every rendered input, output, trigger
   payload, tx summary, approval message and error is scrubbed of every declared
   `secret:`, every secret-typed config field (signer creds, channel tokens, the
   server bearer, `http_call` headers/hmac, `command.env`, …) **and** every
   `${VAR}` env value the raw config references, before it leaves the process.
   The marker is `<redacted>`. This is the same scrubber the
   [archive exporter](/operations/retention-and-archive#rflow-archive-export)
   uses — one redaction discipline, everywhere.
3. **Filterability.** Runs filter by workflow, status, trigger kind, network,
   contract, relayer, tx hash, block, run id, step id, error kind, approval
   status, session (live / replay / test) and time range — backed by guarded,
   idempotent database indexes for the common ones.

### The embedded UI — `GET /`

Open `http://localhost:3940/` while `rflow start` is running. It is a single
dependency-free HTML/CSS/JS file embedded in the binary — **no build step, no
external CDN, works offline**. Views:

| View                        | Answers                                                                                                                                                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workflows overview**      | per workflow: pause state, trigger kind, last run / success / failure, success & failure counts, runs waiting, median / p95 duration, tx count, recent error kind, cursor / head lag                                                                        |
| **Runs history**            | the full filter/search set above, reflected in the URL hash so a filtered view is shareable                                                                                                                                                                 |
| **Run detail** (timeline)   | trigger summary, condition results, step timeline with redacted inputs/outputs, retries & attempts, simulation result, gas-cap checks, approval decisions, tx lifecycle, wait/delay parking, reorg linkage, replay/test marker                              |
| **Transactions**            | every send rflow attempted or would have sent — network, relayer, status lifecycle, tx hash, idempotency key, explorer link where the network resolves                                                                                                      |
| **Approvals**               | pending + decided, who decided and why                                                                                                                                                                                                                      |
| **Waiting**                 | runs parked right now (tx / delay / event / approval), with due/expiry                                                                                                                                                                                      |
| **Failures & dead-letters** | failed and dead-lettered runs                                                                                                                                                                                                                               |
| **Reorg responses**         | durable `on_reorg` responses and their steps                                                                                                                                                                                                                |
| **Replay/test sessions**    | isolated backtest/dry-run sessions and their run counts                                                                                                                                                                                                     |
| **Relayers** (address book) | every relayer wallet: network, address + copy button, live balance with low-balance flag, [funding-plan](/config/relayers#funding-operations) estimate/shortfall, recent gas spend — backed by `GET /api/relayers`; a row deep-links to that relayer's runs |

The UI is deliberately restrained (dense tables with durable column widths, copy
buttons on every hash/id/address, clear `<redacted>` markers, dark + light
themes, loading/error/empty states). **Untrusted run data is never rendered as
HTML** — event args, errors and HTTP bodies reach the DOM only as text, so a
value containing a `<script>` tag shows as text and never executes.

### The JSON API — `GET /api/history/*`

Read-only, cursor-paginated, redacted, and gated by the same bearer as the rest
of `/api/*`. List endpoints return `{ "items": [...], "cursor": "<opaque|null>",
"has_more": <bool> }`; pass `cursor` back as a query param to page.

| Endpoint                             | Returns                                                                                                                                                                                                                           |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/history/runs`              | runs page (filters via query params: `workflow`, `status`, `trigger`, `network`, `contract`, `relayer`, `tx_hash`, `block`, `run_id`, `step_id`, `error_kind`, `approval_status`, `session`, `since`, `until`, `limit`, `cursor`) |
| `GET /api/history/runs/:id/timeline` | one run's chronological timeline: `{ run, events: [...] }` where each event is a `trigger`, `step`, `approval` or `reorg_step`                                                                                                    |
| `GET /api/history/txs`               | send attempts (queued/parked/submitted/settled)                                                                                                                                                                                   |
| `GET /api/history/approvals`         | approvals (pending + decided)                                                                                                                                                                                                     |
| `GET /api/history/waiting`           | runs parked right now                                                                                                                                                                                                             |
| `GET /api/history/reorgs`            | durable `on_reorg` responses                                                                                                                                                                                                      |
| `GET /api/history/replays`           | replay/test sessions                                                                                                                                                                                                              |
| `GET /api/history/workflows`         | the per-workflow overview that powers the landing page                                                                                                                                                                            |
| `GET /api/history/export`            | `?format=json` → `{ runs, steps, sends, approvals, failures }` (`application/json`); `?format=csv` → a flat runs CSV (`text/csv`). Redacted; no raw-payload flag.                                                                 |

```bash
# newest 50 runs of one workflow, then the next page
curl -s -H "Authorization: Bearer $RFLOW_API_TOKEN" \
  'localhost:3940/api/history/runs?workflow=treasury-sweep&limit=50' | jq '.cursor'
curl -s -H "Authorization: Bearer $RFLOW_API_TOKEN" \
  'localhost:3940/api/history/runs?workflow=treasury-sweep&limit=50&cursor=<cursor>' | jq '.items | length'
```

Bad cursors / malformed run ids answer `400 {"error": ...}`; an unknown run id
answers `404`. Since the layer is read-only, `since` accepts a duration (`24h`,
`7d`) or an RFC3339 timestamp.

### The CLI

Everything the UI shows is reachable over SSH without it — see the
[`rflow history`](/cli#rflow-history) and [`rflow runs`](/cli#rflow-runs)
references:

```bash
rflow history --status failed --since 24h           # what failed today
rflow history txs --since 7d                         # what money moved this week
rflow history waiting                                # what's parked right now
rflow history approvals --all                        # every decision, not just pending
rflow history export --workflow treasury-sweep --since 30d --format csv --out audit.csv
rflow runs diff <run-a> <run-b>                      # a good run vs a bad one
rflow runs timeline <run-id>                         # one run, chronologically
```

Each list command prints a `next page: --cursor <c>` hint when more rows exist,
and `--json` emits the same `{ items, cursor, has_more }` shape the API returns.

### Authentication

By default rflow's port is unauthenticated (localhost / private-network
operator tool). Set [`config.server.auth.token`](/config/config#server--optional)
to require a bearer on `/` and `/api/*`:

```yaml [rflow.yaml]
config:
  server:
    auth:
      token: "${{ secrets.RFLOW_API_TOKEN }}"   # never a yaml literal
```

With auth on:

* the **UI shell at `GET /` stays public** — it is a secret-free static login
  page that must load unauthenticated so the browser can prompt for the token.
  Every `/api/*` request (including `/api/history/*`) then requires
  `Authorization: Bearer <token>`.
* the UI shows a clean **login card** on any `401`, stores the token in
  `sessionStorage`, sends it on every API call, and returns to login on a later
  `401`. The token is never rendered or logged.
* **behind an auth-terminating proxy** (oauth2-proxy, Cloudflare Access, most
  tunnels and embedded preview browsers) the `Authorization` header is often
  stripped or replaced with the proxy's own bearer. The server therefore also
  accepts the token via an `X-Rflow-Token` request header, and the UI falls
  back to it automatically when a login `401`s despite a sent token. Caveat:
  log/APM pipelines that redact `Authorization` by default usually record
  custom headers verbatim — the UI only uses the fallback in environments that
  actually need it, but if your intermediary captures request headers into
  logs, treat those logs as secret or rotate with `rflow token revoke`.
* `/health` stays open for k8s probes (unless `health_public: false`);
  `/metrics` follows auth unless `metrics_public: true`. `/hooks/*` webhook
  routes keep their own per-trigger HMAC `auth:` and are never covered by the
  bearer.

Beyond the shared token you can mint named, revocable bearers with
[`rflow token`](/cli) — any of them authenticates the API and UI.

### Explorer links

The transactions and run-detail views build per-network block-explorer links
from a built-in chain map (keyed on the network name / chain id). Networks that
don't resolve to a known explorer simply show the hash with a copy button and no
link. All links open in a new tab with `rel="noopener"`.

### Retention

The explorer reads history; it never prunes it. Bounding the journal is the job
of [`config.retention` + `rflow retention`/`rflow archive`](/operations/retention-and-archive),
which share the exact same redaction discipline — an exported audit trail never
leaks a secret whether it comes from `rflow history export` or `rflow archive
export`.


## Safety lint & the CI gate

`rflow validate` answers *"is this config correct?"* — `rflow lint` answers
*"is it safe to run in production?"*. A workflow can be perfectly valid YAML
and still broadcast unsimulated sends with no gas ceiling off an
unauthenticated webhook. Lint holds every workflow against a **policy**: the
recommended defaults out of the box, tunable via an optional top-level
`policy:` block. `rflow ci` wraps lint, validate and every other unattended
check into one command with one exit code.

```bash
rflow lint                      # recommended policy - warnings advise, exit 0
rflow lint --strict             # warnings fail - the CI posture
rflow lint --profile prod       # lint the prod-merged view (and its policy:)
rflow ci                        # the full gate
rflow ci --profile prod --json  # machine report for GitHub Actions
```

Lint is **fully static** — no database, no network, and usually no `.env`
needed (it prefers the raw `${VAR}` view of `rflow.yaml`; only a placeholder
in a typed non-string field like `chain_id` forces the substituted view and
needs that var set) — so it runs first in any pipeline.

### The severity model

Three honest tiers, so a fresh project is advised rather than blocked:

* **A knob you wrote into `policy:` denies.** You asked for the guarantee —
  its absence is a failure (exit 1).
* **A recommended default warns.** `rflow lint` prints the finding, its fix
  and a docs link, and exits 0.
* **`--strict` (or `policy.strict: true`) promotes every warning to deny.**
  Teams typically ship `strict: true` inside a `prod` profile's `policy:`.

Every finding carries a stable rule id — the key used by suppressions and the
anchors below.

### Rules

#### send-simulation-off

A `send_transaction` sets `simulate: false`. Sends are pre-flight simulated by
default; opting out means a reverting call still broadcasts (and pays gas),
and `assert_sim` / approval previews are skipped. Knob: `require_simulation`
(default `true`).

#### send-no-gas-cap

A send has no gas ceiling: no step `gas.max_price` / `gas.max_cost` **and**
its relayer has no `policy.max_gas_price`. Without one, a gas spike broadcasts
at any price. Knob: `require_gas_caps` (default `true`).

#### send-low-confirmations

A workflow that sends transactions triggers from an on-chain event below the
policy's confirmation depth (`run_on: unconfirmed` counts as depth 0, and
composite `all:`/`any:` triggers match at head). A reorg can orphan the
trigger *after* money moved. Knob: `min_confirmations_for_sends` (default `1`
— head-fired money is flagged; `0` disables). Notify-only workflows are never
flagged — alert at head, pay at depth.

#### send-approval-timeout-proceeds

An approval gate sets `on_timeout: proceed`, so an **unanswered** approval
broadcasts once the timeout elapses. Knob: `allow_approval_timeout_proceed`
(default `false`).

#### send-approval-no-recheck

An approval-gated send has no `recheck:` expression. Approval already
re-simulates before broadcast, but only a recheck re-verifies *your business
condition* after the human delay. Knob: `require_recheck_with_approval`
(default `false` — enable where conditions go stale while a human decides).

#### send-no-spend-guard

A money-moving workflow has neither an attached budget nor
`permissions.max_value_per_tx` — nothing bounds cumulative outflow when
something upstream goes wrong. Knob: `require_spend_guard_for_sends` (default
`false`). See [Budgets](/workflows/budgets).

#### send-no-test-fixture

A money-moving workflow has no `tests/<workflow>*.json` dry-run fixture (the
convention [`rflow ci`](#rflow-ci) runs). Knob:
`require_test_fixtures_for_sends` (default `false`).

#### relayer-budget-required

A send uses a relayer listed in `require_budget_for_relayers`, but no attached
budget covers that relayer. This knob only exists explicitly, so a violation
**always fails** — and a typo'd relayer name in the policy is itself flagged
(`policy-invalid`) rather than silently protecting nothing.

#### catch-up-sends

A money-moving cron/interval workflow sets `catch_up: true`: after downtime,
every missed slot fires — a burst of sends against conditions that may no
longer hold. Knob: `allow_catch_up_for_sends` (default `false`).

#### relayer-underfunded

A money-moving send targets a relayer on a network with no
[`automatic_top_up`](/config/networks#rrelayer-passthroughs) funding safety
net: if the relayer runs low on gas, sends stall silently until an operator
tops it up. Lint is static (CI never touches the chain), so this checks the
*configuration posture* — the live balance-vs-need comparison is `rflow
doctor`'s `relayer.<name>.funding.<network>` check and
[`rflow relayers funding-plan`](/config/relayers#funding-operations).
Monitor-only: warns by default, denies under `--strict`.

#### webhook-no-auth

A webhook trigger accepts unauthenticated requests. An open route is remote
control of whatever the workflow does — money or not — so this fires on every
webhook without `auth: hmac`. Knob: `require_webhook_auth` (default `true`).

#### webhook-send-no-idempotency

A webhook whose workflow sends has no `idempotency_key`. Webhook delivery is
at-least-once: a caller retry (timeout, 5xx, network blip) becomes a *second*
money-moving run. Knob: `require_webhook_idempotency_for_sends` (default
`true`).

#### server-unauthenticated

The project moves money and rflow's port binds publicly (the zero-config
default is `0.0.0.0`) with no `config.server.auth` — the run viewer and
`/api/*` are open to anyone who can reach the port. Satisfied by an auth
token *or* a loopback `config.server.bind`. Knob: `require_server_auth`
(default `true`; never fires on monitoring-only projects). See
[Self-hosting](/self-hosting).

#### policy-invalid

The `policy:` block itself is inconsistent — a suppression naming an unknown
rule or workflow, an empty `reason`, or `require_budget_for_relayers` listing
a relayer that does not exist. Always denies, and cannot be suppressed.

#### policy-unused-suppression

A `policy.suppress` entry matched no finding. Stale suppressions rot — remove
it (or fix its scope).

### The `policy:` block

Every knob is optional; absent knobs use the recommended default. Written
knobs deny on violation.

```yaml
policy:
  strict: false                            # true = every warning fails
  require_simulation: true
  require_gas_caps: true
  min_confirmations_for_sends: 2
  allow_approval_timeout_proceed: false
  require_recheck_with_approval: false
  require_spend_guard_for_sends: false
  require_budget_for_relayers: [treasury]  # violations always fail
  allow_catch_up_for_sends: false
  require_webhook_auth: true
  require_webhook_idempotency_for_sends: true
  require_server_auth: true
  require_test_fixtures_for_sends: false
```

A profile can carry its own `policy:` — it replaces the top-level block
wholesale when `--profile` is passed, so prod states its complete posture:

```yaml
profiles:
  prod:
    policy:
      strict: true
      min_confirmations_for_sends: 12
      require_spend_guard_for_sends: true
      require_test_fixtures_for_sends: true
```

### Suppressions (with a required reason)

Silence a specific finding under `policy.suppress`. `reason` is **mandatory —
the file does not parse without it** — and every suppression is echoed in the
report with its reason, so the justification stays visible in CI logs.
Optional `workflow:` and `step:` narrow the scope; an entry that matches
nothing is flagged as [`policy-unused-suppression`](#policy-unused-suppression).

```yaml
policy:
  suppress:
    - rule: server-unauthenticated
      reason: "port is firewalled to the ops VPN"
    - rule: send-no-gas-cap
      workflow: liquidate
      step: fire
      reason: "liquidation protection must land at any gas price"
```

### rflow ci

One command, one exit code — everything that fits an unattended pipeline, in
order. Stages that need something the environment does not have (a database,
fixtures, a committed schema copy) are **skipped and say why**, never
silently passed:

| stage          | what it checks                                                                                     | when it is skipped                 |
| -------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `ci.validate`  | strict collect-all validation ([`rflow validate`](/cli#rflow-validate))                            | never                              |
| `ci.lint`      | this page's safety lint (`--strict` promotes)                                                      | never                              |
| `ci.schema`    | a committed `rflow.schema.json` matches this CLI (`rflow schema > rflow.schema.json`)              | no schema copy in the project      |
| `ci.templates` | `.rflow/template-lock.yaml` entries resolve in the registry (version drift is visible, non-gating) | no lock file                       |
| `ci.plan`      | [config plan](/operations/versioning-and-plan) vs the latest stored version                        | DB unreachable / no stored version |
| `ci.tests`     | every `tests/<workflow>[.case].json` fixture as a [dry-run test](/backtesting)                     | no fixtures / DB unreachable       |
| `ci.preflight` | live RPC/database/channel connectivity                                                             | unless `--preflight` is passed     |

Exit rule: non-zero iff a gating stage fails (`ci.templates` drift is
informational). `--json` prints a versioned machine report on pure stdout —
diagnostics and the final error go to stderr, so a pipeline can parse stdout
*and* gate on the exit code.

#### Test fixtures convention

Put a fixture for a workflow's own trigger kind at `tests/<workflow>.json`
(more cases: `tests/<workflow>.big-amount.json`). `rflow ci` runs each as
`rflow test <workflow> --fixture <file>` — a dry-run against the real config
where sends simulate but never broadcast. The
[`send-no-test-fixture`](#send-no-test-fixture) rule can require one per
money-moving workflow.

#### GitHub Actions example

```yaml
name: rflow-ci
on: [pull_request]

jobs:
  gate:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_PASSWORD: rflow, POSTGRES_DB: rflow }
        ports: ["5448:5432"]
    env:
      DATABASE_URL: postgres://postgres:rflow@localhost:5448/rflow
      ETH_RPC: ${{ secrets.ETH_RPC }}
    steps:
      - uses: actions/checkout@v4
      - name: Install rflow
        run: curl -fsSL https://rflow.xyz/install.sh | bash
      - name: CI gate
        run: rflow ci --profile prod --json > rflow-ci.json
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with: { name: rflow-ci-report, path: rflow-ci.json }
```

The gate step fails on its own exit code; the JSON artifact carries every
stage row and lint finding (with fix + docs link) for the PR annotation of
your choice — e.g.
`jq -r '.lint.findings[] | "::warning::\(.rule): \(.message)"' rflow-ci.json`.

### Where lint sits among the other checks

* [`rflow validate`](/cli#rflow-validate) — correctness. Unknown keys, broken
  references, malformed values. Hard errors block `rflow start`.
* **`rflow lint`** — safety posture. Static, policy-driven, suppressable.
* [`rflow doctor`](/operations/doctor-and-explain) — operational health of a
  RUNNING setup (balances, cursors, stuck work). Needs the environment.
* [`rflow plan`](/operations/versioning-and-plan) — what a deploy would
  change, against the journal's live state. Needs the database.

`rflow ci` sequences the unattended subset of all four.


## Retention, pruning & archive — bound the journal safely

rflow journals **every** run and step forever by default. That is the right
default — history is how you debug incidents, prove what a keeper did, and
reconstruct a run. But in long-running production the journal grows without
bound, and eventually someone reaches for a manual `DELETE`.

`config.retention` + the `rflow retention` / `rflow archive` commands give you a
**safe, operator-driven** lifecycle for old history instead:

* [`rflow retention plan`](#rflow-retention-plan) — see exactly what *would* be
  pruned, per class, before anything is deleted.
* [`rflow retention prune`](#rflow-retention-prune) — prune it, in one
  cascade-correct transaction per class, only with an explicit `--yes`.
* [`rflow archive export`](#rflow-archive-export) — dump history to redacted
  JSONL for audit or cold storage.

Three guarantees shape all of it:

1. **Absent config == today.** With no `config.retention` block, **nothing is
   ever auto-pruned** — exactly the behaviour before this feature. rflow never
   deletes run history behind your back.
2. **Never delete live state.** Active runs, pending approvals, parked
   `wait_for:` waits, parked delays, in-flight sends and running reorg
   responses are **never** prunable — a run is prunable only if it is terminal,
   old enough, and owns no live durable dependent.
3. **Operator-driven, never a surprise.** There is **no** background pruner and
   **no** delete at boot. Rows disappear only when a human runs `rflow retention
   prune --yes`.

### Configuration

```yaml [rflow.yaml]
config:
  db_connection: postgresql://localhost/rflow
  retention:
    live_runs: 180d          # succeeded/skipped runs older than this are prunable
    replay_sessions: 14d     # disposable `rflow replay` sessions
    test_runs: 30d           # disposable `rflow test` sessions
    failed_runs: keep        # failed/dead_letter runs — default keep (audit-first)
    approvals: keep          # decided approval rows — default keep
    archive_before_prune: true
    archive_path: ./archives
```

Every field is **optional**. Each window is either a duration (`180d`, `14d`,
`12h`) or the literal `keep`; **`keep` is the default** for every window, so a
partial block only opts the classes you name into pruning.

| Field                  | Governs                                               | Default                   |
| ---------------------- | ----------------------------------------------------- | ------------------------- |
| `live_runs`            | `succeeded` + `skipped` (benign terminal) runs        | `keep`                    |
| `failed_runs`          | `failed` + `dead_letter` runs                         | `keep` (audit-preserving) |
| `replay_sessions`      | `rflow replay` sessions (via the replay-prune path)   | `keep`                    |
| `test_runs`            | `rflow test` sessions                                 | `keep`                    |
| `approvals`            | **decided** approval rows (approved/rejected/expired) | `keep`                    |
| `archive_before_prune` | export a redacted archive before deleting             | `false`                   |
| `archive_path`         | where archives are written (relative = project dir)   | `./archives`              |

`failed_runs` and `approvals` default to `keep` on purpose: failures and
approval decisions are the rows you most want to review after an incident.

`rflow validate` checks every window is `keep` or a positive duration and that
`archive_path` is non-empty, so a typo (`live_runs: whenever`) fails fast.

### What is protected

A run is prunable **only if all** of these hold:

* its status is **terminal** for the class (`succeeded`/`skipped` for
  `live_runs`; `failed`/`dead_letter` for `failed_runs`), and
* its `finished_at` is older than the window, and
* it owns **no** live durable dependent — no pending approval, no parked
  `wait_for:` wait, no step parked on a tx/delay/approval/event, and no
  **running** reorg response.

This is enforced as one explicit SQL predicate used by both the plan (counting)
and the prune (deleting), so the two can never drift. The set is stable under a
running executor because terminal runs are immutable — they never sprout new
parked work.

`approvals` prunes only **decided** rows; a pending approval is never touched.
Replay/test sessions are pruned through the existing
[`rflow replay prune`](/backtesting) path, which refuses to delete a live
workflow that collides with the session namespace.

### `rflow retention plan`

Reads only. Reports, per class, how many rows/sessions would be pruned and the
oldest/newest timestamp in that set:

```bash
$ rflow retention plan

treasury - retention plan (as of 2026-08-04 14:30:47 UTC)
 class           | window | prunable    | oldest           | newest
 live_runs       | 180d   | 4210 runs   | 2025-06-01 09:12 | 2026-02-05 23:59
 failed_runs     | keep   | 0 runs      | -                | -
 replay_sessions | 14d    | 3 sessions  | 2026-07-01 10:00 | 2026-07-18 14:22
 test_runs       | 30d    | 0 sessions  | -                | -
 approvals       | keep   | 0 approvals | -                | -
```

### `rflow retention prune`

Prints the same plan, then acts. **Deletion requires `--yes`** — without it,
prune prints the plan and a hint and deletes nothing. `--dry-run` is an explicit
plan-only run.

```bash
rflow retention prune            # prints the plan, refuses (no --yes)
rflow retention prune --dry-run  # prints the plan, exits (never deletes)
rflow retention prune --yes      # actually prunes
```

Each class is deleted in **one transaction**, children first (step rows, reorg
journal, dead-letters, budget reservations, …) so no foreign key is ever left
dangling. When `archive_before_prune: true`, the archive export runs **first**
and must **succeed** — if it fails, the whole prune aborts and **nothing is
deleted**.

### `rflow archive export`

Dumps runs + their steps + sends + approvals + failures + reorg responses +
replay sessions in a date range to a single **JSONL** file, **secrets redacted
by default**:

```bash
rflow archive export --since 2026-01-01
rflow archive export --since 2026-01-01 --until 2026-03-01 --out ./cold-storage
```

`--since`/`--until` are `YYYY-MM-DD` UTC dates (the `--until` day is inclusive;
omit it for "up to now"). Only `--format jsonl` exists today (CSV for selected
tables is a later add).

#### Format

One file, **one JSON object per line**, each tagged with its source table and
ordered deterministically (`(timestamp, id)` within each table):

```json
{"table":"workflow_runs","row":{"id":"…","status":"succeeded","trigger_payload":{…}}}
{"table":"step_runs","row":{"id":"…","run_id":"…","output":{…}}}
```

`sends` are the `send_transaction` rows of `step_runs` (their `external_id` /
`tx_id` / `tx_hash`), so there is no separate `sends` table.

#### Redaction

Every string leaf of every exported row is scrubbed of secret **values** before
it is written, using the same discipline as the
[config-version snapshot](/operations/versioning-and-plan): any field masked by
redaction (declared `secrets:`, signer credentials, channel tokens, the server
bearer, `http_call` headers/hmac, `command.env`, …) contributes its value to the
scrub set, plus every `${VAR}` env value the config references. So a run's
rendered inputs, outputs, trigger payloads and tx summaries **cannot** leak a
secret or an `Authorization` header into the archive.

### Backup & compliance workflow

A common cadence, run from cron or an operator runbook (rflow itself never
schedules it):

1. `rflow archive export --since <last-run-date>` → ship the JSONL to object
   storage / your warehouse loader.
2. `rflow retention plan` → review what will be pruned.
3. `rflow retention prune --yes` → prune (with `archive_before_prune: true` the
   export re-runs and gates the delete, so step 1 is belt-and-braces).

Old replay/test sessions can be reclaimed the same way, or ad-hoc with
[`rflow replay prune --older-than 7d`](/backtesting).

### Non-goals (v1)

* No data-warehouse export, no immutable compliance service, no cloud-storage
  integration — archives are local JSONL you move where you like.
* No background auto-delete: retention is **operator-driven** through the CLI.
* CSV export lands later; JSONL is the v1 format.


## Spend tracking — what rflow actually paid

Budgets cap what a send *may* spend; operators also need to know what rflow
*did* spend. Spend tracking is a durable, receipt-derived ledger
(`rflow.native_spend`) written at every send's terminal settle, answering:
*how much native gas did rflow burn — by workflow, by relayer, by network —
how much native value moved, and how much gas was lost to reverted
transactions?*

It ships as three surfaces over one ledger, so the numbers can never diverge:

* a **CLI** — [`rflow spend`](/cli#rflow-spend) (grouped summary) and
  `rflow spend export` (raw entries, CSV/JSON),
* a **read-only JSON API** — `GET /api/spend` (auth-gated like every `/api/*`
  route),
* a **Spend view** in the [history explorer](/operations/history-explorer)
  (`GET /` → Spend).

And one enforcement hook: a budget's
[`max_gas_spend`](/workflows/budgets#max_gas_spend--the-gas-circuit-breaker)
cap refuses further sends once the *recorded* gas spend in its window reaches
the cap.

### What is captured

When a send reaches a **terminal state where a transaction landed on-chain**,
rflow reads the receipt (the relayer's journaled receipt when it carries gas
numbers, otherwise one `eth_getTransactionReceipt` over the read providers)
and records:

| column                | meaning                                                                                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gas_used`            | The receipt's `gasUsed`.                                                                                                                                                                       |
| `effective_gas_price` | The receipt's `effectiveGasPrice` (falls back to the legacy `gasPrice` on pre-EIP-1559 chains).                                                                                                |
| `gas_spend_wei`       | `gas_used × effective_gas_price`, **plus the receipt's `l1Fee` when present** (the OP-stack L1 data fee Base/Optimism debit on top of the L2 execution fee) — what the chain actually charged. |
| `value_wei`           | The native value the send **moved** (from the journaled send value). **Zero for reverted sends** — a revert burns gas but transfers nothing.                                                   |
| `reverted`            | Whether the transaction reverted on-chain (its gas is the *reverted loss* subtotal).                                                                                                           |

Every row is attributed to the **workflow, run, step, relayer, network and
chain id** of the send, plus the transaction hash and a `recorded_at`
timestamp — the three query dimensions (workflow / relayer / network) are
indexed.

Capture discipline — honest limits included:

* **Best-effort, never blocking.** The ledger is operator accounting, not part
  of the money path: a failed receipt fetch logs a warning and never fails the
  step. A gap in the ledger is possible; a broken send because of the ledger
  is not.
* **Idempotent.** Rows are keyed `UNIQUE (step_run_id, tx_hash)` and inserted
  with `ON CONFLICT DO NOTHING`, so a crash-rerun of the same terminal settle
  never double-counts.
* **Only landed transactions.** Confirmed sends and reverted sends (status
  `FAILED` with a receipt) are recorded. Dropped / expired / replaced sends
  never landed, so there is nothing to record. Sends with
  `wait_for: none | submitted` settle *before* a receipt exists — their spend
  is recorded only if a receipt is already available at settle time, so
  fire-and-forget sends can be under-counted.
* **Native currency only.** ERC20 flows are budget territory
  ([`max_token_value`](/workflows/budgets)); there is no fiat conversion.
* **Top-ups are recorded too.** A
  [`rflow relayers topup`](/config/relayers#funding-operations) send lands in
  the ledger under the synthetic workflow name `relayers.topup` (attributed to
  the *funding* relayer), so relayer-funding gas shows up in the same summaries
  — alongside its `rflow.operator_audit` row (`rflow relayers history`).

### Retention

`rflow.native_spend` deliberately has **no foreign key** onto the run journal:
like the operator audit trail, spend history is an accounting record that
survives [retention pruning](/operations/retention-and-archive) of the runs it
describes. Pruning old runs never touches recorded spend.

### Budget integration — `max_gas_spend`

A [budget](/workflows/budgets) may declare a gas circuit breaker:

```yaml
budgets:
  solver-gas:
    window: 24h
    max_gas_spend: 1 ether        # wei literal, like max_native_value
    scope:
      relayers: [solver]
```

Before every in-scope send broadcasts, rflow sums the **recorded** gas spend
inside the budget's scope and window; once that total has reached the cap the
send fails `budget_exceeded` — same failure taxonomy, same
before-any-broadcast guarantee as the value caps.

**Recorded-spend semantics, on purpose.** Unlike `max_native_value` this is
*not* a reservation: actual gas is only known at the receipt, and pre-send
estimates are unreliable (nodes over- and under-estimate, prices move between
estimate and inclusion, L2 fee components are invisible pre-send). Charging
estimates would either falsely refuse sends or leave phantom spend in the
window. The cap is therefore a **circuit breaker over settled truth, not a
precise limiter**: sends already in flight when the cap is reached can
overshoot it by their own gas before their receipts land in the ledger. Size
the cap with that headroom in mind.

### CLI

```bash
rflow spend                                        # grouped summary: by workflow / relayer / network + totals
rflow spend --workflow treasury-sweep --since 30d  # filter any dimension + time range
rflow spend --relayer solver --network base --json # exact wei, machine-readable
rflow spend export --format csv                    # raw entries (stable columns), stdout
rflow spend export --format json --since 7d        # { "entries": [...] }
```

Human tables format amounts as the native unit; `--json` and `export` carry
exact wei (decimal strings — uint256 does not fit JSON numbers). The CSV
columns are a stable contract:
`recorded_at,workflow,relayer,network,chain_id,tx_hash,gas_used,effective_gas_price,gas_spend_wei,value_wei,reverted,run_id,step_run_id`.

### API

`GET /api/spend` accepts `workflow`, `relayer`, `network`, `since` (`24h`,
`30d` or RFC3339) and `limit` (entries page size, default 50, max 500) as
query parameters and returns:

```json
{
  "summary": {
    "by_workflow": [ { "key": "treasury-sweep", "tx_count": 12, "gas_spend_wei": "…", "value_wei": "…", "reverted_count": 0, "reverted_gas_wei": "0" } ],
    "by_relayer":  [ { "key": "solver", "…": "…" } ],
    "by_network":  [ { "key": "base", "…": "…" } ],
    "total":       { "tx_count": 12, "gas_spend_wei": "…", "value_wei": "…", "reverted_count": 0, "reverted_gas_wei": "0" }
  },
  "entries": [ { "recorded_at": "…", "workflow": "…", "relayer": "…", "network": "…", "chain_id": 8453, "tx_hash": "0x…", "gas_spend_wei": "…", "value_wei": "…", "reverted": false, "run_id": "…", "step_run_id": "…" } ]
}
```

The summary always aggregates the **full** filtered ledger; `limit` only pages
the entries. The endpoint is gated by the same bearer auth as every `/api/*`
route and served `Cache-Control: no-store`.

### Explorer

The **Spend** view in the embedded explorer shows the same summary — KPI tiles
(gas spend, value moved, reverted loss, send count), one table per dimension
(clicking a row filters to it) and the newest settled sends with explorer
links. Filters (workflow / relayer / network / time range) live in the URL
hash like every other view.


## State inspection & repair — supported recovery, not manual SQL

A durable workflow engine will eventually get something stuck: a bridge message
that never arrives leaves a saga parked on a `wait_for:` forever; a bad RPC or
config trips a circuit breaker; an approval nobody answers sits pending; an
indexer falls behind and a cursor needs re-scanning. When that happens you need
**supported, journal-aware repair commands** — not a `psql` prompt and a prayer.

rflow gives you two tiers:

* **Read-only inspection** — [`rflow state inspect`](#rflow-state-inspect) plus
  `cursors ls` / `waits ls` / `delays ls` / `circuit ls` / `approvals ls`. Look
  before you touch anything.
* **Narrow repair mutations** — one command per known stuck state, each with
  explicit domain semantics, a **plan printed first**, a required `--yes`, and an
  **audit row** written in the same transaction as the fix.

Three guarantees shape all of it:

1. **A repair can never create a duplicate send or corrupt exactly-once state.**
   No repair touches a run with an in-flight send (`waiting_tx`). Terminalizing a
   stuck wait *fails* the run — it never re-runs a money-moving step with a new
   idempotency key.
2. **Prefer terminalizing over deleting.** Repairs settle stuck work to a
   terminal status; they never delete run history or edit a step's output.
3. **Every mutation is auditable.** Each applied repair writes one
   `rflow.operator_audit` row (`action`, `target`, `args`, `reason`, `actor`,
   `created_at`) inside the same transaction that made the change — so the fix
   exists in history iff it actually happened, and `rflow archive export` can dump
   it.

Each mutation runs as **one transaction that re-checks its precondition** under a
row lock, so the plan you saw and the change you applied can never disagree
(no TOCTOU). A precondition that no longer holds is **refused**, changing nothing
— which also makes every command idempotent under a re-run.

### `rflow state inspect`

The durable-state dashboard. Read-only; every query is a plain `SELECT`.

```bash
rflow state inspect                      # everything
rflow state inspect --workflow treasury-sweep
rflow state inspect --json               # machine-readable snapshot
```

It reports run counts by status, parked saga waits, parked delays (with
`wake_at`), pending approvals, trigger cursors, circuit-breaker state,
replay/test session leftovers, and a tail of recent operator repairs. The
scoped read-only listings back the same data:

```bash
rflow cursors ls [--workflow <wf>]
rflow waits ls   [--workflow <wf>]
rflow delays ls  [--workflow <wf>]
rflow circuit ls [--workflow <wf>]
rflow approvals ls [--all]
```

### Repair commands

Every repair prints its plan and refuses without `--yes`:

```bash
$ rflow circuit reset treasury-sweep
PLAN: reset circuit breaker 'treasury-sweep'
  current state: open
action: close the breaker, clear its failure window, and resume the workflow if the breaker paused it (an operator's own pause stands).
refusing to reset without --yes. This is the plan; re-run with `--yes` to apply it.
```

#### `rflow cursors set <workflow> <network> --block <n> --yes`

Moves a trigger cursor's last-processed block to re-scan or skip ahead.

* **Lowering** re-scans the range. Events already claimed dedupe by the
  `workflow_runs (workflow_name, trigger_key)` UNIQUE constraint, so a re-scan
  **cannot create a duplicate run or a duplicate send** — only genuinely
  *unclaimed* matches in the range fire. The plan warns loudly.
* **Raising** skips the range — unprocessed events in it are permanently skipped.
* Refused below the deployment anchor, or when already at the target block.

#### `rflow waits cancel <run-id> --reason "<why>" --yes`

Cancels a saga stuck on a `wait_for:` — **terminalizes** the run to `failed`
with your reason and drops its open event-wait rows. History is never deleted.
Refused if the run is not actually parked on a wait (`waiting_event`), which
includes any run holding an in-flight send.

#### `rflow delays wake <run-id> --yes`

Wakes a parked durable delay early by setting the delay step's `wake_at` to now.
A **running engine keeps the run parked in memory until its *original* wake
time** and never re-scans `waiting_delay` runs, so the early wake is applied on
the next **engine restart / failover recovery pass** — restart or fail over to
resume it now. It only re-arms the durable timer — the resume path is
exactly-once by `external_id`, so no send is duplicated. Refused if the run is
not `waiting_delay`, or if the delay is already due.

#### `rflow approvals expire <id> --yes`

Expires a pending approval so the run takes its approval **`on_timeout`** path
— exactly as a natural timeout would. The command itself never broadcasts, but
it does **not** cancel the send: the running engine then applies `on_timeout`,
and that depends on the mode.

* **`on_timeout: fail`** (the default): the parked send is dropped and never
  broadcast.
* **`on_timeout: proceed`**: the timeout is treated as consent, so the running
  engine **BROADCASTS the parked send**. The plan warns loudly in this case —
  expiring is *not* a way to abort a `proceed` gate.

Refused if the approval is not pending.

#### `rflow circuit reset <workflow> --yes`

Closes a tripped breaker, clears its failure window, and resumes the workflow —
but **only** if the breaker itself paused it (`paused_by = circuit_breaker`). An
operator's own `rflow workflow pause` during the incident always stands. Refused
if the breaker is already closed.

### Doctor points you at the fix

`rflow doctor --deep` detects these stuck states and names the exact repair
command in its hint: a stale cursor → `rflow cursors set`, a stuck wait past its
timeout → `rflow waits cancel`, a tripped breaker → `rflow circuit reset`, a
stale pending approval → `rflow approvals expire`.

### Non-goals

There is **no** general SQL console, **no** arbitrary step-output editing, and
**no** replaying of completed money-moving steps with new idempotency keys. Those
are exactly the operations that would break exactly-once, so they are out of
scope by design.


## Unattended ops — alerting when nobody is watching

Automation you don't watch needs to tell you two things on its own: **"a run
broke"** and — the harder one — **"nothing is happening when something
should be"**. rflow ships three journal-backed guarantees for that:

1. the [`workflow_error` meta-trigger](#the-workflow_error-meta-trigger) —
   run failures fire a workflow, so your alerting is itself a workflow
2. [per-workflow liveness](#liveness--alert-when-a-workflow-goes-silent) —
   alert when a workflow claims no run past `max_silence`
3. [indexer stall detection](#indexer-stall-detection) — alert when the
   chain moves but the trigger cursors don't.

All three journal their state in Postgres, so alerts are **bounded** (one
per incident, not one per tick) and survive restarts.

### The `workflow_error` meta-trigger

A trigger whose source is other workflows' failures:

```yaml
workflows:
  on-any-failure:
    trigger:
      workflow_error:
        workflows: "*"          # one name, a list, or '*' for everything
        on: [dead_letter]       # default; add `failed` for on_failure: drop|halt
    steps:
      - id: page
        http_call:
          url: https://ops.example.com/rflow-failures
          body:
            workflow: "${{ trigger.failed.workflow }}"
            run: "${{ trigger.failed.run_id }}"
            step: "${{ trigger.failed.step_id }}"
            kind: "${{ trigger.failed.error.kind }}"
            message: "${{ trigger.failed.error.message }}"
```

#### The trigger context

| Path                                               | Description                                                                                    |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `trigger.failed.workflow`                          | The workflow whose run settled badly                                                           |
| `trigger.failed.run_id`                            | The source run id                                                                              |
| `trigger.failed.trigger_key`                       | What fired the source run                                                                      |
| `trigger.failed.status`                            | `dead_letter` \| `failed`                                                                      |
| `trigger.failed.step_id`, `trigger.failed.attempt` | The failing step                                                                               |
| `trigger.failed.error.kind`                        | The [failure taxonomy](/workflows#retries-and-the-failure-taxonomy) kind, e.g. `assert_failed` |
| `trigger.failed.error.message`                     | The journaled (secret-redacted) message                                                        |
| `trigger.observed_at`                              | When the failure settled                                                                       |

#### Guarantees

* **Exactly once per settled source run**: the watcher claims
  `wferr:{source_run_id}` through the normal claim gate. A `rflow runs
  retry` that dead-letters the *same* run again re-fires nothing; matrix
  combinations are distinct runs and fire individually.
* **Recursion guard**: a workflow whose own trigger is `workflow_error`
  never fires other watchers — a broken alerter logs loudly instead of
  starting an alert storm. (`'*'` therefore never matches another watcher.)
* Watchers fire on the **engine settle path, live mode only** —
  [`rflow replay` / `rflow test`](/backtesting) rehearsal runs never feed
  them, and paused watchers skip.

#### Honest limits

* A workflow can't watch itself, and `rflow validate` errors on unknown or
  empty `workflows:` entries (watcher-watching-watcher is a warning — the
  guard means it never fires).
* Two settle paths deliberately do **not** fire watchers: runs dead-lettered
  because the workflow *definition changed* under them, and
  `on_conflict`-superseded runs — both are deliberate operator/config
  outcomes, not production failures.

### Liveness — alert when a workflow goes silent

Failures page you; *silence* is what unattended deployments die of. Declare
how often a workflow is expected to fire:

```yaml
workflows:
  deposit-mirror:
    liveness:
      max_silence: 30m         # expected to claim a run at least this often
      notify: [ops]            # notifications.channels entries
    trigger:
      event: { contract: Vault, name: Deposit, network: base }
    steps: [...]
```

* The signal is the most recent run **claim** (any status) — silence means
  "nothing even fired", which catches dead trigger sources (RPC rot, an
  upstream contract migration, a paused feed) long before failure counts
  would.
* **One alert per breach**: a `rflow.liveness_events` row opens with the
  breach (that row is the dedupe gate), and a "recovered" notice goes out
  when a new run claims. A re-breach is a new row and a new alert.
* **Boot anchor**: silence is measured from the later of the last claim and
  the stack boot — a stack that was down all weekend doesn't page you the
  moment it boots; every workflow gets a full quiet window first.
* **Paused workflows are exempt** — pausing is an operator decision, not an
  outage. Pausing closes an open breach quietly.

`rflow status` prints the liveness table (last run, `max_silence`,
OK/BREACHED); [`/health`](/observability#json-api) reports `degraded` with
the breach in `reasons[]` while one is open; `/metrics` carries
`rflow_liveness_breached{workflow}`.

### Indexer stall detection

The whole-pipeline version of liveness: if the chain **head advances** while
every event-trigger cursor on a network is **frozen** past a window, the
indexing pipeline is stalled — even though no workflow "failed".

```yaml
config:
  monitoring:
    indexer_stall_after: 5m    # default 5m
    notify: [ops]
```

Semantics chosen to avoid false pages:

* a cursor that is *behind but moving* (historical backfill) is never a
  stall
* an unreachable RPC stays quiet here (the head can't be observed — that's a
  network problem, visible elsewhere)
* boot floors the comparison, so a fresh boot never instant-alerts.

Stalls journal under the synthetic subject `__indexer:<network>` in the same
`rflow.liveness_events` table, degrade `/health`, raise
`rflow_indexer_stalled{network}` and alert `monitoring.notify` channels once
per stall.

### Severity mapping

Liveness and stall alerts ride the same
[notification channels](/config/notifications) as everything else. For
pager-style channels the severity says "unattended deployment went dark":

| Alert                              | PagerDuty  | Opsgenie |
| ---------------------------------- | ---------- | -------- |
| Liveness breach / indexer stall    | `critical` | `P1`     |
| Circuit-breaker trip               | `critical` | `P1`     |
| `notify:` step run-failure reports | `error`    | `P3`     |
| Approval requests                  | `info`     | `P5`     |

Slack/Discord/Telegram/webhook channels get the plain message; Twilio gets
an SMS.

### Honest notes

* The monitor loop runs **on the leader instance only** (the one holding the
  project lock) and evaluates every **60 seconds** (plus 0–10s boot jitter).
  `max_silence: 5s` is honored, but *detection* lands on the next tick — up
  to \~60s later. Treat the tick as the alerting resolution; there is no
  sub-minute paging.
* Monitor tasks are lazy: nothing runs unless some workflow declares
  `liveness:` or `config.monitoring` is set. The boot banner prints a
  `monitor:` line when they start.
* Alert *sending* is best-effort with the journal as truth: if every channel
  errors, the breach row still exists (visible in `/health`, `/metrics`,
  `rflow status`) and the `notified` column records the delivery failure —
  rflow does not retry-spam a broken channel every tick.


## Versioning & config plan — audit every deploy

Every run should be traceable to the **exact** config that produced it, and
every config change should be **reviewable before it goes live**. rflow builds
this in: it fingerprints your `rflow.yaml` on every boot, stamps that version
onto every run, and gives you a semantic `plan` that flags dangerous changes
(and the parked work they collide with) before a restart.

* [`rflow versions`](#config-versions) — the deployed-config history
* [`rflow plan`](#rflow-plan--the-deploy-gate) — the pre-deploy diff + safety gate
* [`rflow rollback`](#rflow-rollback) — reconstruct an old version to disk

### Config versions

On every `rflow start`, rflow **canonicalizes** the fully profile-merged
config — deterministically, with **every declared secret redacted** — and
`sha256`s it. If that hash differs from any stored version, it inserts a new
row in `rflow.config_versions` with an id like `20260802143011-b7e2c9`
(`<UTC timestamp>-<short hash>`). An unchanged config re-uses the existing
version, so restarts never churn the history.

The version identity is over **structure, not secrets**: rotating a
`${VAR}`-provided key, a signer mnemonic (top-level *or* per-network), a channel
token, a block-explorer `api_keys` entry, an `http_call` header or the API
bearer never mints a new version, but any real change — a step, a trigger, a cap
— does. Before hashing, a declared secret *field* is masked to `<redacted>` and
a value *interpolated* from `${VAR}` (an Infura key inside an RPC url, a
`Bearer` header, a command arg) is restored to that `${VAR}` placeholder — so
the skeleton (host, path, arg positions) survives while the secret does not.
**No secret value ever lands in `rflow.config_versions` or its hash.**

Every run created thereafter is stamped with the current `config_version`
alongside its per-workflow `config_hash` (the resume fence). The two **agree**:
both are copied from the workflow mirror the same boot wrote. You can see the
version anywhere runs appear:

```bash
rflow runs show <id>     # version   20260802143011-b7e2c9  +  config sha256:…
rflow ls                 # a `version` column per workflow
```

```bash
rflow versions ls                 # id, hash, created, run count
rflow versions show <id>          # summary + per-workflow definitions
rflow versions diff <a> <b>       # the semantic delta between two versions
```

`ls` and `diff` accept `--json` for automation.

:::tip
One project = one database. Config versions live in the shared `rflow` schema
(like workflows, runs and cursors), so point every instance of a project at the
same Postgres and give distinct projects distinct databases.
:::

### `rflow plan` — the deploy gate

`rflow plan` answers *"is it safe to restart with this change?"*. It computes
the **semantic diff** from a baseline (the newest stored version by default, or
`--from-version <id>`) to a target (`./rflow.yaml`, or `--to <path>`), then
overlays **active runtime conflicts** from the journal.

```bash
rflow plan                                   # newest version -> ./rflow.yaml
rflow plan --from-version <id> --to ./next.yaml --profile prod
rflow plan --json                            # machine-readable (CI)
```

Every finding carries a **severity**:

| severity  | meaning                                                             |
| --------- | ------------------------------------------------------------------- |
| `error`   | cannot apply safely — `rflow plan` **exits non-zero** (the CI gate) |
| `warning` | can apply, but review it                                            |
| `info`    | a normal change                                                     |

#### What the diff understands

It reasons over the typed config, not text:

* **workflows** added / removed / **renamed** (a body-identical rename is
  detected, and flagged because run history stays under the old name)
* **triggers**: a changed kind, a `start_block` change (backfill vs skip
  history), **lowered confirmations** (reorg exposure), a `run_on` change
* **steps — especially money-moving `send_transaction`** (in the main chain,
  `on_reorg` compensation, or `finally`): a send added, removed, or changed
  (relayer / network / target / function / args / raw `data` calldata / value /
  multicall / gas policy), plus a **weakened guard** — `simulate` disabled, or
  `assert_sim` / `recheck` removed
* **approval policy**: an approval gate removed, or `on_timeout` weakened to
  `proceed` (broadcasts with nobody approving) — both are warnings
* **relayer / signer** changes (a secret *rotation* is not a change)
* **budgets & rate limits**: a raised or removed cap is a weakened guard
* **contract** address / ABI changes, and **profile** overlay diffs

#### Runtime conflicts

A change is not safe in a vacuum. If a workflow being **removed** or **changed**
has parked or in-flight work — a waiting approval, a parked delay, a `wait_for:`
park, or an in-flight send — `plan` raises it:

* **removed** with parked work → **error** (that work would be stranded)
* **changed** with parked work → **warning**

```text
error  treasury-sweep  runtime-conflict-removed  workflow 'treasury-sweep' is
       being removed but has 1 parked/in-flight run(s) — 1 waiting approval(s)
```

Wire `rflow plan` into CI before a deploy: a non-zero exit blocks the merge
until the error-severity items (or the parked work they name) are resolved.

### `rflow rollback`

`rflow rollback <version-id>` reconstructs a stored version back into an
`rflow.yaml`:

```bash
rflow rollback 20260802143011-b7e2c9                 # print to stdout (default)
rflow rollback 20260802143011-b7e2c9 --output ./rflow.yaml --yes
```

Writing to a file backs up the current one first (`rflow.yaml.bak`).

**Honesty about redaction:** the stored snapshot is redacted, so rollback
restores the committed **structure** with secret fields as `<redacted>` and
`${VAR}`-interpolated values back as their placeholder. It is not a secrets
backup — real values still come from your `.env`/`${VAR}` exactly as before.
Rollback restores *shape*; fill the placeholders from your environment.

### Non-goals

rflow versioning is **not** a replacement for Git, and `plan` does not
auto-guess a safe migration for every trigger change — it **reports** dangerous
changes so a human (or CI) decides. Git tracks your text; rflow understands its
own runtime semantics.


## Migrating from OpenZeppelin Defender

OpenZeppelin Defender was sunset on July 1, 2026. If you ran Monitors, Relayers and
Actions there, rflow covers the same ground — self-hosted, in one binary, with
stronger execution guarantees. This page maps every Defender concept to its rflow
equivalent and shows the one-command importer.

### The one command

If you managed Defender with the
[`defender-as-code`](https://github.com/OpenZeppelin/defender-as-code) serverless
plugin, point the importer at your `serverless.yml`:

```bash
rflow import defender ./serverless.yml --output ./my-project
```

It scaffolds a complete project — `rflow.yaml`, `.env` / `.env.example`, `abis/`,
`docker-compose.yml` and a `MIGRATION-NOTES.md` — and prints a summary table of what
mapped, what needs review, and what could not be converted. The generated project
**passes `rflow validate` as-is**: everything that has no rflow equivalent yet stays
in the file as a clearly-marked `# TODO(rflow import)` comment instead of being
silently dropped.

```
 status          | source item                                | result
 mapped          | monitor 'large-usdc-transfers' event ...   | → workflow 'large-usdc-transfers'
 mapped          | relayer 'relayer-2'                        | merged into relayers.payout-relayer
 needs attention | action 'daily-reporter'                    | cron mapped; the JS body does NOT auto-convert
 needs attention | action 'action-webhook'                    | webhook trigger mapped; the JS body does NOT auto-convert

imported into ./my-project - 9 mapped, 12 need attention, 3 not migrated
```

### Concept map — Defender gave you X, in rflow it is Y

| Defender                                          | rflow                                                                                                                                                                                                                                                                                       | Imported automatically?                                                                                                                                                                                     |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Monitor (event condition)                         | workflow with an [`event:` trigger](/workflows/triggers/event)                                                                                                                                                                                                                              | ✅ one workflow per event signature                                                                                                                                                                          |
| Monitor condition expression (`value > 100`)      | `where: "${{ trigger.args.value > 100 }}"`                                                                                                                                                                                                                                                  | ✅ best-effort translated, flagged for review                                                                                                                                                                |
| Monitor `confirm-level`                           | trigger `confirmations: N \| finalized`                                                                                                                                                                                                                                                     | ✅                                                                                                                                                                                                           |
| Monitor function / transaction conditions         | no direct equivalent — watch an emitted event, or use a [`read:` trigger](/workflows/triggers/read) (poll a view function, fire on a threshold)                                                                                                                                             | ❌ TODO comment + note                                                                                                                                                                                       |
| Notification channel (slack / telegram / discord) | [`notifications.channels`](/config/notifications) + [`notify`](/workflows/steps/notify) steps                                                                                                                                                                                               | ✅ credentials via `.env`                                                                                                                                                                                    |
| Notification channel (pagerduty / opsgenie)       | native [`pagerduty:` / `opsgenie:` channels](/config/notifications)                                                                                                                                                                                                                         | ✅ credentials via `.env`                                                                                                                                                                                    |
| Notification channel (email / datadog)            | an [`http_call`](/workflows/steps/http-call) to the provider's API                                                                                                                                                                                                                          | ❌ noted                                                                                                                                                                                                     |
| Notification channel (webhook)                    | [`http_call`](/workflows/steps/http-call) step with templated body + optional HMAC                                                                                                                                                                                                          | ❌ noted (one-liner to add)                                                                                                                                                                                  |
| Relayer                                           | [`relayers:`](/config/relayers) entry                                                                                                                                                                                                                                                       | ✅                                                                                                                                                                                                           |
| `address-from-relayer`                            | one relayer on several networks — rflow creates the wallet once and clones the address everywhere                                                                                                                                                                                           | ✅ merged into a single entry                                                                                                                                                                                |
| Relayer policy (gas cap, receiver allowlist)      | [`relayers.<name>.policy`](/config/relayers#policy--per-relayer-guard-rails) (`max_gas_price`, `whitelist_receivers`) + per-workflow `permissions.max_value_per_tx`                                                                                                                         | ❌ noted with the exact keys to set                                                                                                                                                                          |
| Relayer `min-balance`                             | `automatic_top_up` passthrough on the network (relayers fund each other / from a Safe)                                                                                                                                                                                                      | ❌ noted                                                                                                                                                                                                     |
| Monitor alert threshold (X events in Y)           | trigger [`throttle:`](/workflows/triggers/event#throttle)                                                                                                                                                                                                                                   | ✅ semantics caveat flagged — Defender alerts on the Nth hit, rflow runs the first N then cools down                                                                                                         |
| Action (schedule: cron or frequency)              | workflow with a [`cron:` trigger](/workflows/triggers/cron)                                                                                                                                                                                                                                 | ✅ trigger only — see below                                                                                                                                                                                  |
| Action JavaScript body                            | native steps ([`read`](/workflows/steps/read), [`http_call`](/workflows/steps/http-call), [`send_transaction`](/workflows/steps/send-transaction), [`notify`](/workflows/steps/notify)) where they fit; otherwise keep the JS and run it from a [`command:`](/workflows/steps/command) step | ❌ logic cannot auto-convert, but a `command:` step runs your preserved script as-is — it decides/prepares and a later `send_transaction` moves money. A TODO placeholder keeps the workflow valid meanwhile |
| Action (webhook trigger)                          | a [`webhook:` trigger](/workflows/triggers/webhook) (`path` + optional HMAC auth)                                                                                                                                                                                                           | ✅ trigger only — point callers at rflow's port; the JS body stays a TODO                                                                                                                                    |
| Action environment variables                      | [`constants:`](/config/constants-secrets-lists)                                                                                                                                                                                                                                             | ✅                                                                                                                                                                                                           |
| Secrets                                           | [`secrets:`](/config/constants-secrets-lists) backed by `.env` placeholders                                                                                                                                                                                                                 | ✅ names only — Defender never exposes secret **values**, re-enter them                                                                                                                                      |
| Contracts + ABIs                                  | [`contracts:`](/config/contracts) registry; `${file(...)}` ABIs are copied, missing ones are synthesized from the monitored event signatures                                                                                                                                                | ✅                                                                                                                                                                                                           |

### The two honest caveats

**Your relayer keys do not come with you.** Defender custodied the signing keys and
they were never exportable. The importer scaffolds a fresh
[`signer:`](/config/signer) (dev mnemonic via `.env`, or swap in AWS KMS / GCP /
Turnkey / Fireblocks / Privy / PKCS#11) — you get **new** relayer addresses. Fund
them, and update any onchain allowlists that referenced the old Defender addresses.
`rflow relayers ls` shows the new addresses after first start.

**JavaScript does not become YAML.** Autotask/Action code bodies are real programs;
converting them mechanically would be dishonest. The importer converts the *trigger*
(schedule → cron) and leaves a placeholder step with a TODO pointing at your source
file. Most action bodies port in minutes: an onchain check becomes `read:` +
`assert:`, an API call becomes `http_call:`, a transaction becomes
`send_transaction:` (which also gets you pre-flight simulation and idempotency keys
for free).

### Worked example

A typical Defender monitor:

```yaml [serverless.yml]
monitors:
  large-usdc-transfers:
    name: 'Large USDC Transfers'
    type: 'BLOCK'
    network: 'mainnet'
    addresses:
      - '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
    confirm-level: 1
    notify-config:
      channels:
        - ${self:resources.notifications.slack-1}
    conditions:
      event:
        - signature: 'Transfer(address,address,uint256)'
          expression: 'value > 10000000000'
```

becomes:

```yaml [rflow.yaml (generated)]
contracts:
  large-usdc-transfers-target:
    abi: ./abis/large-usdc-transfers-target.json # synthesized from the event signature
    addresses:
      ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

notifications:
  channels:
    workspace-slack:
      slack:
        webhook_url: ${WORKSPACE_SLACK_WEBHOOK_URL}

workflows:
  large-usdc-transfers:
    trigger:
      event:
        contract: large-usdc-transfers-target
        name: Transfer
        network: ethereum
        where: "${{ trigger.args.value > 10000000000 }}"
        confirmations: 1
        start_block: latest
        end_block: live
    steps:
      - id: notify-workspace-slack
        notify:
          channel: workspace-slack
          message: "Large USDC Transfers: Transfer on ethereum - tx ${{ trigger.tx_hash }}"
    on_failure: dead_letter
```

Then:

```bash
cd my-project
docker compose up -d   # postgres
vim .env               # rpc urls, slack webhook, signer
rflow validate
rflow start
```

### Holding OpenZeppelin Monitor (OSS) configs instead?

OpenZeppelin's suggested Defender replacement,
[`openzeppelin-monitor`](https://github.com/OpenZeppelin/openzeppelin-monitor), uses
JSON monitor files whose shape is very close to what rflow imports —
`match_conditions.events[].signature/expression` map 1:1 onto `event:` triggers with
`where:`, and its `triggers` (slack/telegram/discord/webhook/script) map onto
`notifications.channels` and steps. A dedicated `rflow import oz-monitor` is planned;
until it lands, the table above is the translation guide — and unlike a
monitor-only tool, the same file that watches the event can also **send the
response transaction**.

### What you gain in the move

* **Exactly-once execution** — journaled steps + idempotency keys instead of
  best-effort retries. See [Reliability](/reliability).
* **Pre-flight simulation on every send** by default — plus
  [gas caps, `assert_sim` and `recheck`](/workflows/steps/send-transaction).
* **Reorg-aware confirmations per trigger** — alert at head, pay at depth, and
  [`on_reorg:` compensations](/reorgs#actionable-reorg-responses--on_reorg)
  Defender never had. See [Reorgs](/reorgs).
* **Historical backfill + live tail in one config** (`start_block: earliest`) —
  and [`rflow replay`](/backtesting) to backtest a workflow before it goes live.
* **Human approval gates** on transactions — see [Approvals](/approvals).
* **Your custody** — keys never live in a vendor's cloud again.


## Migrating from Gelato

Gelato deprecated Web3 Functions on March 31, 2026, and the classic Automate task
products are winding down with them. Time-based tasks, event listeners and recurring
contract calls all have direct rflow equivalents — self-hosted, with exactly-once
execution instead of best-effort. This page maps every Gelato concept and shows the
one-command importer.

### The one command

Export your task definitions as JSON (the same shape as the
[`automate-sdk`](https://github.com/gelatodigital/automate-sdk) `createTask` /
`createBatchExecTask` options, plus a `chainId`) and run:

```bash
rflow import gelato ./tasks.json --output ./my-project
```

The input file may hold one task object, an array of tasks, or
`{ "tasks": [...] }`:

```json [tasks.json]
[
  {
    "name": "Oracle Keeper",
    "chainId": 1,
    "trigger": { "type": 1, "cron": "*/10 * * * *" },
    "web3FunctionHash": "QmPXsYNiw...",
    "web3FunctionArgs": { "oracle": "0x71B9...4da", "currency": "ethereum" }
  },
  {
    "name": "Counter Increment",
    "chainId": 84532,
    "trigger": { "type": 0, "interval": 300000 },
    "execAddress": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
    "execSelector": "0xe8927fbc",
    "dedicatedMsgSender": true
  }
]
```

`trigger.type` is the SDK's `TriggerType` enum — numeric (`0` TIME, `1` CRON, `2`
EVENT, `3` BLOCK) or the spelled-out string, both work.

The importer scaffolds a complete project (`rflow.yaml`, `.env` / `.env.example`,
`abis/`, `docker-compose.yml`, `MIGRATION-NOTES.md`) that **passes `rflow validate`
as-is**, with every unconvertible piece kept visible as a `# TODO(rflow import)`
comment plus a MIGRATION-NOTES entry — nothing is silently dropped.

### Concept map — Gelato gave you X, in rflow it is Y

| Gelato                                                   | rflow                                                                                                                                                                                                                                                                                         | Imported automatically?                                                                                                                                                                                                                                     |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CRON trigger                                             | workflow with a [`cron:` trigger](/workflows/triggers/cron)                                                                                                                                                                                                                                   | ✅ expression verbatim                                                                                                                                                                                                                                       |
| TIME trigger (interval ms)                               | workflow with an [`interval:` trigger](/workflows/triggers/interval)                                                                                                                                                                                                                          | ✅ the millisecond cadence maps to `every:` faithfully (rflow is second-granular, so sub-second or non-round intervals round to the nearest second and are flagged)                                                                                          |
| EVENT trigger (`filter.address` + topics)                | workflow with an [`event:` trigger](/workflows/triggers/event)                                                                                                                                                                                                                                | ⚠️ the topic hash can't be reversed into an event name — but if an ABI json next to the export (or in its `abis/` dir) declares that topic0, the real event name + ABI are used; otherwise a placeholder is written and flagged                             |
| `blockConfirmations`                                     | trigger `confirmations: N`                                                                                                                                                                                                                                                                    | ✅                                                                                                                                                                                                                                                           |
| BLOCK trigger (every block)                              | a [`block:` trigger](/workflows/triggers/block) — `block: { every: 1, network: ... }`                                                                                                                                                                                                         | ✅ raise `every:` to run less often                                                                                                                                                                                                                          |
| Classic task (`execAddress` + `execSelector`/`execData`) | [`send_transaction`](/workflows/steps/send-transaction) step from a scaffolded relayer                                                                                                                                                                                                        | ✅ selector-only calldata is flagged if the function takes arguments                                                                                                                                                                                         |
| Resolver contract (checker)                              | `read:` step with `assert:` (or an `if:`) before the send                                                                                                                                                                                                                                     | ❌ noted — port the checker logic                                                                                                                                                                                                                            |
| `dedicatedMsgSender`                                     | a named [relayer](/config/relayers) — your workflows share one address per chain                                                                                                                                                                                                              | ⚠️ new address: update onchain whitelists (`rflow relayers ls` shows it)                                                                                                                                                                                    |
| `web3FunctionArgs` / `userArgs`                          | [`constants:`](/config/constants-secrets-lists) — `${{ constants.<name> }}` in steps                                                                                                                                                                                                          | ✅                                                                                                                                                                                                                                                           |
| Web3 Function TypeScript body                            | native steps ([`read`](/workflows/steps/read), [`http_call`](/workflows/steps/http-call), [`send_transaction`](/workflows/steps/send-transaction), [`notify`](/workflows/steps/notify)) where they fit; otherwise keep the code and run it from a [`command:`](/workflows/steps/command) step | ❌ logic cannot auto-convert, but a `command:` step runs your preserved Web3 Function as-is — it returns JSON that a later `send_transaction` consumes, so rflow keeps signing/simulation/idempotency. A TODO placeholder keeps the workflow valid meanwhile |
| W3F secrets                                              | [`secrets:`](/config/constants-secrets-lists) backed by `.env`                                                                                                                                                                                                                                | manual                                                                                                                                                                                                                                                      |
| Gelato executors + 1Balance                              | the embedded relayer: your own funded wallet, automatic gas bumping/rebroadcast, optional `automatic_top_up`                                                                                                                                                                                  | ✅ scaffolded (fund the new signer)                                                                                                                                                                                                                          |

### The two honest caveats

**msg.sender changes.** Gelato executed through its own executors /
`dedicatedMsgSender` proxy. rflow sends from **your** relayer wallet — the importer
scaffolds a fresh [`signer:`](/config/signer) plus a `main` relayer. Fund it and
update any contract whitelist that expected the Gelato sender.

**TypeScript does not become YAML.** A Web3 Function is a real program; the importer
converts the *trigger* faithfully and leaves a placeholder step naming the W3F hash
or path to port. Most W3F bodies port in minutes: the offchain fetch becomes
`http_call:`, the onchain check becomes `read:` + `assert:`, and the returned
calldata becomes `send_transaction:` — which also gets you pre-flight simulation,
idempotency keys and a durable journal for free.

### Worked example

The five-minute counter task above becomes:

```yaml [rflow.yaml (generated)]
relayers:
  # scaffolded to replace Gelato's dedicated msg.sender
  main:
    networks: [base-sepolia]

workflows:
  counter-increment:
    trigger:
      interval:
        # Gelato interval: 300000ms
        every: 5m
    steps:
      - id: exec-call
        send_transaction:
          network: base-sepolia
          relayer: main
          to: "0x5FbDB2315678afecb367f032d93F642f64180aa3"
          data: "0xe8927fbc"
    on_failure: dead_letter
```

Then:

```bash
cd my-project
docker compose up -d   # postgres
vim .env               # rpc urls + fresh signer mnemonic
rflow validate
rflow start
```

For event tasks, drop the contracts' ABI json files next to your task export
(or in an `abis/` dir beside it) **before** importing — the importer matches
each task's topic hash against them and writes the real event name + ABI. If
none matched, finish the one flagged TODO: the topic hash is kept in a comment
right above the placeholder, and the comment names the two helpers —
[`rflow abi find-event <file|dir> <topic0>`](/cli#rflow-abi) to match it against
ABIs you already have, and `rflow abi fetch --network <net> --address <0x..>`
to pull the verified ABI from sourcify/etherscan.

### What you gain in the move

* **Exactly-once execution** — every trigger occurrence is claimed once in Postgres,
  every send carries an idempotency key. Survives `kill -9`. See
  [Reliability](/reliability).
* **Pre-flight simulation on every send** by default — reverts are caught before gas
  is spent, plus [gas caps and `assert_sim` gates](/workflows/steps/send-transaction).
* **Reorg-aware event triggers** — `confirmations: 0 | N | finalized` per trigger,
  with [`on_reorg:` responses](/reorgs#actionable-reorg-responses--on_reorg).
  See [Reorgs](/reorgs).
* **Backtesting** — [`rflow replay`](/backtesting) rehearses a workflow over real
  historical blocks before it goes live; Gelato had no equivalent.
* **Human approval gates** on transactions — see [Approvals](/approvals).
* **No per-execution fees** — your infra, your RPC, open source.
* **Off-chain automations too** — cron → HTTP → Telegram with zero networks
  configured.


## What is rflow?

rflow is an open-source, self-hosted onchain workflow engine. You describe automations
in one `rflow.yaml` — *when this event fires on this chain, and this condition holds,
send this transaction over there, then tell me about it* — and rflow runs them with
exactly-once execution, pre-flight simulation, reorg awareness, and a durable journal
you can inspect at any time.

The positioning in one sentence: **GitHub-Actions-shaped YAML gets exactly-once,
reorg-aware, simulation-gated onchain automation — self-hosted, any custody, any EVM
chain.**

### One binary, three engines

rflow embeds two battle-tested Rust libraries in a single process:

| Concern                                                                                                                                                | Owner                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| Block fetching, event decoding, reorg detection, factory tracking, historical backfill                                                                 | [rindexer](https://rindexer.xyz) (embedded) |
| Nonce management, gas pricing & bumping, rebroadcast, tx expiry, signing (9 providers), allowlists, automatic top-up                                   | [rrelayer](https://rrelayer.xyz) (embedded) |
| Workflow state machine, exactly-once journal, expressions, simulation gate, approval gates, sagas, backtesting, notifications, HTTP, cursors, CLI, MCP | rflow                                       |

Events flow in through the embedded indexer, expressions and the step journal run
in-process, and transactions go out through the embedded relayer — all function calls,
no HTTP hop on the hot path. State lives in a single Postgres database (schemas:
`rflow`, `relayer`, `rindexer`).

The engines are lazy: the relayer only boots if you declare a `signer`/`relayers`
block, and the indexer only boots if you have chain triggers. A monitoring-only
project needs no keys; a cron → HTTP → Telegram project needs no networks at all.

### What a workflow looks like

```yaml
workflows:
  mirror:
    trigger:
      event:
        contract: USDC
        name: Transfer
        network: ethereum
        where: "${{ trigger.args.value > wei('1000', 6) }}"
        confirmations: 12
    steps:
      - id: gate
        read:
          contract: USDC
          network: base
          function: "balanceOf(address)"
          args: ["${{ relayers.payout.address }}"]
          assert: "${{ output >= trigger.args.value }}"
      - id: mirror
        send_transaction:
          network: base
          relayer: payout
          contract: USDC
          function: "transfer(address,uint256)"
          args: ["${{ trigger.args.to }}", "${{ trigger.args.value }}"]
          valid_for: 5m
          wait_for: confirmed
      - id: report
        notify:
          channel: ops
          message: "mirrored ${{ format_units(trigger.args.value, 6) }} USDC — ${{ steps.mirror.tx.hash }}"
    on_failure: dead_letter
```

Steps run strictly sequentially. Any prior step's output is addressable from any later
step through the [expression language](/workflows/expressions). Sends are pre-flight
simulated by default and carry an idempotency key, so a crash mid-run can never
double-spend — see [Reliability](/reliability).

### What rflow is not

* **Not a hosted service.** You run it — your infra, your keys (or your KMS/Privy/
  Turnkey/Fireblocks — any of rrelayer's 9 signing providers), your Postgres.
* **Not a smart-contract framework.** rflow reacts to chains and sends transactions;
  it does not deploy or manage contracts.
* **Not an indexer replacement.** If you want a full indexing platform (GraphQL
  APIs, custom schemas, non-workflow consumers), use rindexer directly. rflow uses
  indexing as a trigger surface — and lets workflows make decisions over the event
  tables it already writes via [`query:`](/workflows/steps/query) (with
  [`index_events`](/config/contracts#index_events--index-only-analytics) to index
  extra contracts for exactly that) — but its tables serve workflows, not apps.


## Why rflow?

rflow is Artemis without writing Rust, Defender without the vendor, Temporal without
the SDK — a single fast binary where GitHub-Actions-shaped YAML gets exactly-once,
reorg-aware, simulation-gated automation. Self-hosted, any custody, any EVM chain —
or no chain at all.

### How it compares

|                                                     | rflow                                                                                                                      | OpenZeppelin Defender       | Tenderly Web3 Actions        | Gelato Functions      | Goldsky                       |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------- | --------------------- | ----------------------------- |
| Self-hosted                                         | ✅ single binary + Postgres                                                                                                 | ❌ SaaS                      | ❌ SaaS                       | ❌ network + SaaS      | ❌ SaaS                        |
| Custody                                             | Any — raw keys, AWS KMS, GCP, Privy, Turnkey, Fireblocks, PKCS#11, …                                                       | Defender Relayers hold keys | Bring-your-own signing in JS | Gelato executors      | n/a (data only)               |
| Automation language                                 | Declarative YAML + expressions                                                                                             | JS autotasks                | JS/TS actions                | Solidity/TS functions | pipelines/SQL (no tx sending) |
| Exactly-once execution                              | ✅ journal + idempotency keys, survives `kill -9`                                                                           | best-effort                 | best-effort                  | onchain dedicated     | n/a                           |
| Pre-flight simulation gate                          | ✅ default on every send                                                                                                    | manual                      | ✅ (their infra)              | ✅                     | n/a                           |
| Reorg awareness                                     | ✅ per-trigger `confirmations: 0 \| N \| finalized` + [`on_reorg:` responses](/reorgs#actionable-reorg-responses--on_reorg) | limited                     | limited                      | n/a                   | ✅ (data)                      |
| Backtesting against real history                    | ✅ [`rflow replay` / `rflow test`](/backtesting), dry-run by default                                                        | ❌                           | ❌                            | ❌                     | n/a                           |
| Human approval gates on transactions                | ✅ [`approval:`](/approvals) — telegram/CLI, journaled                                                                      | ✅ (multisig proposals)      | ❌                            | ❌                     | n/a                           |
| Historical backfill + live in one config            | ✅ `start_block`/`end_block` cursors                                                                                        | ❌                           | ❌                            | ❌                     | ✅ (data)                      |
| Cross-chain (event on A → tx on B)                  | ✅ one file, same wallet address per chain + [`wait_for` sagas](/workflows/steps/wait-for)                                  | manual wiring               | manual wiring                | manual wiring         | ❌                             |
| Off-chain-only automations (cron → HTTP → Telegram) | ✅ zero networks needed                                                                                                     | partial                     | partial                      | ❌                     | ❌                             |
| AI-agent operability                                | ✅ built-in [MCP server](/mcp) (`rflow mcp`)                                                                                | ❌                           | ❌                            | ❌                     | ❌                             |
| Pricing                                             | free, open source                                                                                                          | per-usage SaaS              | per-usage SaaS               | per-execution fees    | per-usage SaaS                |

### The differentiators

**Exactly-once, honestly.** Every trigger occurrence is claimed once in Postgres, every
step is journaled before its side effect, and every transaction carries a
client-generated idempotency key enforced by a unique index. Kill the process mid-run
and restart: the run resumes after the last completed step, and an ambiguous send is
resolved by lookup — never re-fired blindly. [Read the details](/reliability); we also
document what is *not* guaranteed.

**Reorg-aware where it matters.** Confirmations are per-trigger, so the same event can
alert at head (`confirmations: 0`) and pay at depth. `rflow validate` prints per-chain
depth advice and warns when a head-fired trigger sends funds. See
[Reorgs](/reorgs).

**The relayer problems are already solved.** Nonce management, gas pricing, gas
bumping, rebroadcast, stuck-tx replacement, per-relayer allowlists and automatic
top-ups are rrelayer's job, embedded in-process. rflow never re-implements them —
once a transaction is queued, rrelayer owns it.

**No vendor, no ports.** The engines are internal; rflow exposes a single
health/status port. Everything runs on your machine against your RPC endpoints, and
your signing keys never leave your custody model.

**Fast.** Event decode → expression eval → relayer send are in-process function calls;
no HTTP or serialization on the hot path. WebSocket head tracking gets triggers firing
the moment a block lands.


## Examples

Runnable, self-contained example projects live in the repo's
[`examples/`](https://github.com/joshstevens19/rflow/tree/master/examples)
directory. Each one is a complete rflow project (`rflow.yaml` + `abis/` +
`Makefile` + `README.md`) driven entirely by make — you type a few targets,
watch the logs, and see real transactions relayed to CONFIRMED. Every example
uses its own database, anvil port and health port, so they can all run side
by side.

**One command, one terminal** — from the repo root, each example runs
end-to-end (chain up, postgres up, deploy/fund, rflow booted, trigger fired
automatically once indexing is live; Ctrl-C cleans up):

```bash
make run-token-transfer-relay
make run-mainnet-fork-usdc
make run-ops-monitor
make run-liquidation-keeper
make run-erc7683-solver
make run-treasury-ops
make run-command-decision
make run-command-trade-prep
make run-template-gallery
```

The per-example 3-terminal walkthroughs remain for step-by-step control:

| example                                                                                                  | what it shows                                                                                                                                                                                                                                                                                                                         | one command (repo root)         | step-by-step                                                        |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------- |
| [token-transfer-relay](https://github.com/joshstevens19/rflow/tree/master/examples/token-transfer-relay) | **The headline.** Watch ERC20 deposits into a treasury address; deposits >= 100 tokens are echoed back out through the embedded rrelayer to CONFIRMED. Zero external deps — local anvil, deterministic addresses.                                                                                                                     | `make run-token-transfer-relay` | `make anvil` · `make setup deploy start` · `make trigger`           |
| [mainnet-fork-usdc](https://github.com/joshstevens19/rflow/tree/master/examples/mainnet-fork-usdc)       | The same relay flow against **real mainnet USDC** on an anvil fork — deposits fired by impersonating a Circle-scale whale, forwarded onward by the relayer.                                                                                                                                                                           | `make run-mainnet-fork-usdc`    | `make anvil-fork` · `make setup fund start` · `make trigger`        |
| [ops-monitor](https://github.com/joshstevens19/rflow/tree/master/examples/ops-monitor)                   | **No signer, no relayer, no event trigger** — lazy boot proven in the logs. A 15s cron reads `totalSupply` on-chain and POSTs HMAC-signed reports to a local Python sink; plus an optional (paused) telegram heartbeat.                                                                                                               | `make run-ops-monitor`          | `make anvil` · `make sink` · `make setup deploy start`              |
| [liquidation-keeper](https://github.com/joshstevens19/rflow/tree/master/examples/liquidation-keeper)     | **The classic keeper bot as one yaml file.** A `read:` trigger polls an Aave-style `healthFactor` every 5s (edge-triggered, no indexer needed); the moment the position goes underwater the keeper liquidates — pre-flight simulated, `assert_sim`-guarded, gas-capped.                                                               | `make run-liquidation-keeper`   | `make anvil` · `make setup deploy start` · `make trigger`           |
| [erc7683-solver](https://github.com/joshstevens19/rflow/tree/master/examples/erc7683-solver)             | **The intents starter kit.** ERC-7683-shaped `Open` events are indexed, quoted (`where:` drops unprofitable intents), race-checked, then approved + filled by the solver relayer — index → decide → simulate → fill → exactly-once, with a commented cross-chain variant.                                                             | `make run-erc7683-solver`       | `make anvil` · `make setup deploy start` · `make trigger`           |
| [treasury-ops](https://github.com/joshstevens19/rflow/tree/master/examples/treasury-ops)                 | **Human-in-the-loop, hands-on.** A 30s cron reads the hot treasury balance and parks a sweep-to-cold behind an `approval:` gate — decide it with `rflow approve` and it rechecks, re-simulates and broadcasts. `on_conflict: skip` keeps parked sends from stacking.                                                                  | `make run-treasury-ops`         | `make anvil` · `make setup deploy start` · `make approvals approve` |
| [command-decision](https://github.com/joshstevens19/rflow/tree/master/examples/command-decision)         | **[`command`](/workflows/steps/command) custom logic, no signer.** A `node` script reads the trigger context on stdin and prints a JSON decision (`{severity, reason}`); later steps branch on it — always report, `if:` non-ok escalate — over an HMAC-signed sink. The command decides; rflow reads the chain, journals, and calls. | `make run-command-decision`     | `make anvil` · `make sink` · `make setup deploy start`              |
| [command-trade-prep](https://github.com/joshstevens19/rflow/tree/master/examples/command-trade-prep)     | **[`command`](/workflows/steps/command) prepares money movement.** A deposit fires a `node` command that quotes a trade (`amount`, `min_out`, `deadline`, `valid_until`); rflow signs + simulates + sends it, gas-capped and `recheck`ed against the freshness window, to CONFIRMED. The command **cannot send** — that is the point. | `make run-command-trade-prep`   | `make anvil` · `make setup deploy start` · `make trigger`           |
| [template-gallery](https://github.com/joshstevens19/rflow/tree/master/examples/template-gallery)         | **The [template registry](/templates) walkthrough.** `rflow templates ls` browses 17 first-party recipes, `rflow new --template` scaffolds a monitor-only AND a money-moving project, `rflow add workflow` composes a dead-letter pager into the first — everything validated. No chain, no database.                                 | `make run-template-gallery`     | `make ls` · `make monitor money add` · `make lock tree`             |

### Prerequisites

* [Foundry](https://getfoundry.sh) (`anvil` + `cast`)
* Docker (postgres via the repo-root `docker-compose.yml`, port 5448)
* Rust (examples run the CLI with `cargo run --bin rflow`)
* `python3` (ops-monitor's sink only)

Each example's `make setup` copies `.env.example` to `.env`, starts postgres
and creates the example's database idempotently. `make help` (the default
target) lists everything else.

:::warning
The mnemonic committed in the examples' `.env.example` files is DEV-ONLY —
it is published so relayer addresses are deterministic and the Makefiles can
pre-fund them. Never hold real funds on it.
:::


## Installation

:::info
rflow uses Postgres for all state and scaffolds a `docker-compose.yml` for you, so it
is recommended to install [docker](https://www.docker.com/products/docker-desktop/) if
you don't have it already.
:::

### Install script

:::warning
If you're on Windows, you will need to install and use Git BASH or WSL as your
terminal, since rflow installation does not support Powershell or Cmd.
:::

:::code-group
```bash [latest]
curl -L https://rflow.xyz/install.sh | bash
```

```bash [exact version]
curl -L https://rflow.xyz/install.sh | bash -s -- --version <version_number>
```
:::

Once installed, check it worked:

```bash
rflow --help
```

The installer also adds two helpers to your PATH:

* `rflowup` — update to the latest release (`rflowup --version X.X.X` for a specific one)
* `rflowdown` — uninstall rflow

### Docker

Every release is published as a docker image:

```bash
docker run --rm ghcr.io/joshstevens19/rflow:latest --help
```

Mount your project directory and point rflow at it:

```bash
docker run --rm -v $(pwd):/app ghcr.io/joshstevens19/rflow:latest start --path /app
```

See [Self-hosting](/self-hosting) for a full compose setup and helm chart.

### From source

```bash
git clone https://github.com/joshstevens19/rflow
cd rflow
cargo install --path crates/cli
```

Requires a recent Rust toolchain (the repo pins one in `rust-toolchain.toml`).

### Next step

Create your first project — [Quickstart](/getting-started/quickstart).


## Quickstart

From nothing to a firing workflow in five commands.

### 1. Install

```bash
curl -L https://rflow.xyz/install.sh | bash
```

### 2. Scaffold a project

```bash
mkdir transfer-alert && cd transfer-alert
rflow new
```

`rflow new` scaffolds from the [template registry](/templates): a picker
lists 17 production-shaped recipes (id + risk + summary — browse them any
time with `rflow templates ls`), then asks one typed prompt per template
input. `--template <id>` pre-selects one; `--yes` skips the prompts entirely
(the `large-transfer-alert` template with its defaults — what this page
follows). Grow the project later with
[`rflow add workflow <template-id>`](/templates/using-templates)
or [`rflow add network|contract|relayer|notification`](/getting-started/scaffolding#rflow-add--grow-an-existing-project),
which append to `rflow.yaml` without disturbing your comments or formatting
(only a chain + address? [`rflow contract add`](/config/abis) fetches the
verified ABI for you).
It writes:

```
transfer-alert/
├── rflow.yaml                    # the project definition
├── abis/erc20.json               # ERC20 ABI used by the workflow
├── docker-compose.yml            # postgres:16 on localhost:5448
├── .env                          # DATABASE_URL, RPC + notification credentials
├── .env.example                  # the same keys, empty — safe to commit
├── .rflow/template-lock.yaml     # which template + answers generated this
└── .gitignore                    # ignores .env and .rflow/
```

The scaffolded `rflow.yaml` is a real, runnable workflow — alert on large USDC
transfers on Ethereum mainnet:

```yaml
rflow_version: 1
name: transfer-alert

config:
  port: 3940
  db_connection: ${DATABASE_URL}
  max_concurrent_runs: 64

networks:
  - name: ethereum
    chain_id: 1
    rpc: ${ETH_RPC}

contracts:
  USDC:
    abi: ./abis/erc20.json
    addresses:
      ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

notifications:
  channels:
    ops:
      telegram:
        bot_token: ${TG_BOT_TOKEN}
        chat_id: ${TG_CHAT_ID}

workflows:
  large-transfer-alert:
    trigger:
      event:
        contract: USDC
        name: Transfer
        network: ethereum
        # fires only above 100000 whole tokens
        where: "${{ trigger.args.value > wei('100000', 6) }}"
        confirmations: 0
        start_block: latest
        end_block: live
    steps:
      - id: alert
        notify:
          channel: ops
          message: "large transfer: ${{ format_units(trigger.args.value, 6) }} USDC in ${{ trigger.tx_hash }}"
    on_failure: dead_letter
```

The scaffolded `.env` points at the compose Postgres and a public RPC:

```bash
DATABASE_URL=postgresql://postgres:rflow@localhost:5448/postgres
POSTGRES_PASSWORD=rflow
ETH_RPC=https://eth.merkle.io
TG_BOT_TOKEN=
TG_CHAT_ID=
```

Fill in `TG_BOT_TOKEN`/`TG_CHAT_ID` (any Telegram bot token + chat), or swap the
channel for `slack: { webhook_url: ... }` / `discord: { webhook_url: ... }`.

### 3. Start Postgres (and anvil, for a local chain)

```bash
docker compose up -d
```

Running against mainnet works as-is. To trigger events yourself, run a local
[anvil](https://getfoundry.sh) chain instead:

```bash
anvil
```

and point the network at it in `rflow.yaml`:

```yaml
networks:
  - name: ethereum
    chain_id: 31337
    rpc: http://localhost:8545
```

Then deploy any ERC20 to anvil and put its address under
`contracts.USDC.addresses.ethereum`.

Check your local dependencies are ready before booting:

```bash
rflow doctor      # Docker, Foundry, Postgres, Node + the rflow.yaml summary
```

`doctor` is informational (it always exits 0) and prints a one-line fix hint for
anything that is `missing`. See [Scaffolding](/getting-started/scaffolding#rflow-doctor--local-readiness).

### 4. Start rflow

```bash
rflow start
```

rflow validates the config (strict — unknown keys are hard errors, and it collects
*all* errors before reporting), applies the `rflow` schema to Postgres, boots the
engines lazily (no signer here, so no relayer boots), and tails the chain from
`start_block: latest`.

### 5. Trigger it

On anvil, fire a qualifying transfer with cast:

```bash
cast send <token-address> "transfer(address,uint256)" \
  0x70997970C51812dc3A010C7d01b50e0d17dc79C8 200000000000 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
```

Watch the run land:

```bash
rflow ls          # workflows: state, trigger, cursor, runs today
rflow runs list   # the journal: per-step status, outputs, attempts
```

Send the same event twice (a reorged duplicate, a replayed block range) and rflow
skips it — the trigger key is claimed exactly once. That's the point.

### Next steps

* Add a [signer and relayers](/config/signer) to send transactions
* Rehearse a workflow against history with [`rflow replay`](/backtesting) —
  or a single fixture with `rflow test`
* Learn the [expression language](/workflows/expressions)
* Understand the [exactly-once guarantees](/reliability)
* Migrating? `rflow import defender ./serverless.yml` /
  `rflow import gelato ./tasks.json` scaffold a project from what you have —
  see [Migrate](/migrate/from-defender)
* Let your editor or AI agent operate the project — [`rflow mcp`](/mcp) and
  [`rflow schema`](/config/profiles#editor-autocomplete-for-rflowyaml)


## Scaffolding & config wizard

rflow is YAML-first — the whole project lives in a `rflow.yaml` you can read,
diff, and review. The scaffold wizard makes the first-run details (RPCs,
networks, contracts, relayers, signers, notifications) fast to get right, without
ever taking the file out of your hands.

Three commands cover the whole lifecycle:

* [`rflow new`](#rflow-new--rflow-init) — create a project (interactive, or one-shot for CI).
* [`rflow add`](#rflow-add--grow-an-existing-project) — grow an existing `rflow.yaml`, one section at a time.
* [`rflow doctor`](#rflow-doctor--local-readiness) — check that Docker/Foundry/Postgres are ready
  (and, inside a project, run the [deep operational suite](/operations/doctor-and-explain)).

### `rflow new` / `rflow init`

```bash
rflow new [--output <dir>] [--name <project-name>] [--template <id>] [--yes]
          [--answer key=value ...] [--answers-file answers.yaml]
```

Interactive on a TTY: a picker lists the [template registry](/templates) —
17 production-shaped recipes, each with an id, a risk label and a summary —
then asks one **typed** prompt per template input (addresses are
checksum-validated, crons parsed, amounts checked; a bad answer is re-asked).
On a non-TTY, or with `--yes`, manifest defaults fill every unanswered input
(the default template is `large-transfer-alert`). It writes the template's
files (`rflow.yaml`, ABIs, `.env` + `.env.example`, `docker-compose.yml` with
postgres on `localhost:5448`, `.gitignore` and a `.rflow/template-lock.yaml`
install record), then runs `rflow validate` and prints the exact next steps.

`--template <id>` picks a template directly — `rflow templates ls` to browse,
`rflow templates show <id>` for its inputs, `--answer key=value` /
`--answers-file` to drive it non-interactively (CI/agents). Legacy scaffold
ids (`transfer-alert`, `cron-report`, `treasury-approval`,
`liquidation-keeper`) resolve to their registry equivalents; `webhook-relay`
and `blank` still use the pre-registry renderer.

A template that requires a signer (the `money_moving` ones) scaffolds a
DEV-ONLY generated mnemonic into `.env` — never into `.env.example` — so the
project validates and boots out of the box; swap in a real signer before
production. `rflow new` refuses to overwrite an existing `rflow.yaml` and
leaves an existing `.env` untouched, so it is safe to re-run in a directory
that already has secrets. See [Using templates](/templates/using-templates)
for the full walkthrough, including `rflow add workflow` composition.

### `rflow add` — grow an existing project

```bash
rflow add [--path <dir>] network       ...
rflow add [--path <dir>] contract      ...
rflow add [--path <dir>] relayer       ...
rflow add [--path <dir>] notification  ...
```

`rflow new` gets you a project; `rflow add` grows it. Each subcommand appends one
entry to the matching top-level section (`networks:`, `contracts:`, `relayers:`,
`notifications.channels:`).

#### It preserves your file byte-for-byte

`add` locates the right section and splices the rendered snippet at the end of that
block. **It does not parse the whole document to a value and re-serialize it** —
that would strip your comments and reflow your formatting. On a money config that
matters. Comments, key ordering, spacing, and the trailing newline all survive; the
only change to the file is the lines that were added. If the section is absent, it
is created; if it is present-but-empty, the first entry fills it.

One expectation: `add` targets the conventional **2-space indentation style**
`rflow new` scaffolds. If a section uses another style (zero-indented list items,
4-space indents), the add is refused with the file untouched and an error that
says so — re-indent the section or add the entry by hand.

#### It validates the merge and refuses to break the file

Before writing, `add`:

1. rejects a **duplicate name** (a network/contract/relayer/channel that already exists),
2. does a light shape check (contract address form, relayer network references), then
3. validates the **merged config in memory** and **refuses (exit 1, file untouched)**
   any change that would introduce a hard validation error.

So `rflow add relayer` on a project with no `signer:` block is refused — a relayer
with nowhere to sign does not validate — and the message tells you why. Errors that
were *already present* in the file before your add are surfaced but do not block
(you asked to add a thing; a pre-existing problem elsewhere is not yours to fix
right now). Every successful add runs `rflow validate` and prints the next
command(s), including a `rflow doctor` hint.

The duplicate-name and reference checks need the current `rflow.yaml` to parse, so
a `${VAR}` placeholder in a strictly-numeric field like `chain_id` (which never
validates) produces a "current config is not valid" message instead of an append —
fix the field first, then add.

#### Interactive, or flag-driven for CI and agents

On a TTY every subcommand prompts (a network-preset picker, a channel-kind menu,
env-var prompts). For CI, agents, and non-TTY shells, pass flags. A non-TTY run
with a required flag missing errors with exactly which flags are needed.

```bash
# a network (preset or custom); --rpc takes a url or a ${ENV} placeholder
rflow add network --name base --chain-id 8453 --rpc '${BASE_RPC}' --confirmations 12

# a contract, single-network or multi-network
rflow add contract --name USDC --abi ./abis/erc20.json --network base --address 0x8335...2913
rflow add contract --name USDC --abi ./abis/erc20.json --addresses ethereum=0xA0b8...eB48,base=0x8335...2913

# no ABI on disk yet? `rflow contract add` fetches the verified one first
# (sourcify -> etherscan) and then runs the same add - see /config/abis
rflow contract add USDC --network ethereum --address 0xA0b8...eB48

# a relayer (needs a signer already configured, else the add is refused)
rflow add relayer --name payout --networks ethereum,base --speed FAST

# a notification channel — one kind flag, plus the env-var names to read secrets from
rflow add notification --name ops --slack --webhook-url-env SLACK_WEBHOOK_URL
rflow add notification --name pager --telegram --bot-token-env TG_BOT_TOKEN --chat-id-env TG_CHAT_ID
```

`--path` is global — it works before or after the subcommand.

**Env-var flags take the variable name, not the secret.** `--webhook-url-env
SLACK_WEBHOOK_URL` renders `webhook_url: ${SLACK_WEBHOOK_URL}` into the YAML, and
you set the real value in `.env`. When you pass only the kind flag, sensible
defaults are used:

| Channel       | Flags                                                     | Default env var(s)                        |
| ------------- | --------------------------------------------------------- | ----------------------------------------- |
| `--telegram`  | `--bot-token-env`, `--chat-id-env`                        | `TG_BOT_TOKEN`, `TG_CHAT_ID`              |
| `--slack`     | `--webhook-url-env`                                       | `SLACK_WEBHOOK_URL`                       |
| `--discord`   | `--webhook-url-env`                                       | `DISCORD_WEBHOOK_URL`                     |
| `--pagerduty` | `--routing-key-env`                                       | `PAGERDUTY_ROUTING_KEY`                   |
| `--opsgenie`  | `--api-key-env` `[--eu]`                                  | `OPSGENIE_API_KEY`                        |
| `--twilio`    | `--account-sid-env`, `--auth-token-env`, `--from`, `--to` | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` |

### `rflow doctor` — local readiness

```bash
rflow doctor [--path <dir>] [--profile <name>] [--deep] [--json]
```

A lean readiness table for the local dependencies rflow needs:

```
rflow doctor
 dependency | status | detail
 docker     | ok     | Docker version 28.5.2, build ecc6942
 anvil      | ok     | anvil Version: 1.6.0-v1.7.0
 cast       | ok     | cast Version: 1.6.0-v1.7.0
 node       | ok     | v25.9.0
 postgres   | ok     | reachable
 rflow.yaml | ok     | valid - 1 workflow(s), 0 warning(s)
```

* **Docker** — daemon reachable (`docker info`).
* **Foundry** — `anvil` and `cast` on `PATH`, with versions.
* **Postgres** — reachable via the project's `config.db_connection` (when a project is present).
* **Node** — optional, for the docs site.
* **rflow\.yaml** — the project's validate summary (workflows + warnings), when a project is found.

Each row is `ok` / `missing` / `n/a`, and any non-ok row prints a one-line "how to
install or start" hint.

When a project is present, the readiness table is followed by the **deep
operational suite** — profile merge, DB schema, RPC chain-id/capability probes,
contract sanity, relayer mappings and balances, channels, webhooks, approval
posture, and coverage notes. Exit code: **non-zero only when an error-severity
check fails**; warnings, advice and info never gate. The full check catalogue,
severities and the CI gating pattern live in
[Doctor & explain](/operations/doctor-and-explain). (For strict collect-all
config errors, use [`rflow validate`](/cli#rflow-validate).)

### A full first run

```bash
rflow new --name payments --template treasury-sweep-approval --yes   # scaffold a sending project
docker compose up -d                                     # postgres on localhost:5448
rflow add network --name base --chain-id 8453 --rpc '${BASE_RPC}'
rflow add contract --name USDC --abi ./abis/erc20.json --network base --address 0x8335...2913
rflow doctor                                             # readiness check
rflow validate                                           # strict, collect-all
rflow start                                              # boot the engines
```


## ABIs — fetch, inspect & discover

Every [contract](/config/contracts) in `rflow.yaml` points at a **committed ABI
json file** (`abi: ./abis/usdc.json`). This page covers the CLI helpers that get
those files onto disk and answer questions about them — fetching the verified
ABI for an address, adding a contract by address alone, inspecting events and
selectors, and reverse-mapping topic hashes.

### `rflow abi fetch` — the verified ABI, by address

```bash
rflow abi fetch --network ethereum --address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --name usdc
rflow abi fetch --chain-id 8453 --address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913   # no project needed
```

Fetches the **verified** ABI for an address and writes it pretty-printed under
the project's `abis/` dir (default `abis/<--name>.json`, or
`abis/<address>.json`; `--out` overrides). Source order:

1. **Sourcify** first — keyless, no account needed.
2. **Etherscan v2** — the multichain API
   (`https://api.etherscan.io/v2/api?chainid=…`), which needs an
   `ETHERSCAN_API_KEY` env var. When the key is absent and Sourcify had no
   match, the error says exactly that, per source.

`--network` reads the chain id from `rflow.yaml`; `--chain-id` works with no
project at all. `--source sourcify|etherscan` pins one source. Re-fetching an
identical file is a no-op, but a file with **different content is never
clobbered** — delete it or pass `--out`.

Honest limits: `fetch` needs outbound network access, only **verified**
contracts resolve, and Sourcify coverage varies by chain — Etherscan (with a
key) is the fallback for exactly that reason. For proxies, the explorer returns
the ABI of the address you give it (often the proxy's own ABI) — fetch the
implementation address when you want the logic events.

### `rflow contract add` — a contract by address alone

```bash
rflow contract add USDC --network ethereum --address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
```

Fetch + wire-up in one step: the verified ABI is fetched (Sourcify →
Etherscan), written to `abis/usdc.json`, and the contract is appended to
`contracts:` through the same comment-preserving, merge-validating code path as
[`rflow add contract`](/getting-started/scaffolding#rflow-add--grow-an-existing-project).
The command prints what was fetched, the file written, and the validate result.

With `--abi <path>` no network is touched — it is exactly `rflow add contract`.

### `rflow abi inspect` — events, topics, selectors

```bash
rflow abi inspect ./abis/usdc.json [--json]
```

```
Events in ./abis/usdc.json
 EVENT    | SIGNATURE                         | TOPIC0                | INDEXED
 Transfer | Transfer(address,address,uint256) | 0xddf252ad…523b3ef    | from: address, to: address

Functions in ./abis/usdc.json
 FUNCTION | SIGNATURE                 | SELECTOR   | MUTABILITY
 transfer | transfer(address,uint256) | 0xa9059cbb | nonpayable
```

Every event with its full signature, **topic0** hash and indexed params; every
function with its **4-byte selector** and mutability. `--json` emits the same
rows for tooling.

### `rflow abi find-event` / `find-function` — reverse lookup

```bash
rflow abi find-event ./abis 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
rflow abi find-event --project 0xddf252ad…                     # every ABI rflow.yaml references
rflow abi find-function ./abis/erc20.json 0xa9059cbb
rflow abi find-function --project "transfer(address,uint256)"  # signatures are hashed for you
```

Maps a topic0 hash back to the event that emits it — against one ABI file, a
directory of ABI json files, or (with `--project`) every ABI the project's
`rflow.yaml` references. `find-function` is the same lookup for 4-byte
selectors and also accepts a full signature. Unparseable json in a directory
scan is skipped with a warning; no match exits 1 with an `rflow abi fetch`
hint.

### "did you mean?" — validation suggests the real name

`rflow validate` checks every event and function a workflow references against
the contract's ABI. When a name doesn't exist but a close match does, the error
says so:

```
- workflow 'large-transfer-alert' trigger: contract 'USDC' has no event 'Transferr' - did you mean 'Transfer'?
```

Case-insensitive exact matches win first, then a small edit-distance search
(cap 2–3); a function signature with the wrong arity suggests the real
signature.

### Importers match topic hashes locally

The [Defender](/migrate/from-defender) and [Gelato](/migrate/from-gelato)
importers never touch the network — but when a Gelato task carries a bare event
topic hash, the importer matches it against ABI json files **next to the export**
(and in an `abis/` dir beside it) and writes the real event name + ABI when one
declares that topic0. Every note about an event it could not name carries the
exact `rflow abi find-event <file|dir> <topic0>` and
`rflow abi fetch --network <net> --address <0x..>` commands to finish the job.

### Why there is no `abi: { fetch: ... }` in rflow\.yaml

Deliberately omitted. A config that fetches ABIs at load time is not
reproducible — a re-verification, an explorer outage, or a proxy upgrade would
change what your money workflows decode. `rflow.yaml` only ever points at
**committed ABI files**; the CLI fetches once and materialises the file, so
`git diff` shows exactly what changed. No config surface changed
(`rflow.schema.json` is untouched).

Full flag reference: [`rflow abi`](/cli#rflow-abi) and
[`rflow contract`](/cli#rflow-contract) in the CLI docs.


## config

Engine-level settings.

```yaml
config:
  port: 3940                       # rflow's ONLY exposed port (health/status)
  db_connection: ${DATABASE_URL}   # required — postgres is the only storage
  max_concurrent_runs: 64          # optional — cap on concurrently executing runs
  # relayer_api:                   # optional — expose the embedded rrelayer REST API
  #   enabled: true
  #   port: 8000
  #   authentication_username: ${RRELAYER_USER}
  #   authentication_password: ${RRELAYER_PASS}
  # ha:                            # optional — leader/standby high availability
  #   standby: true
  #   takeover_poll: 5s
  # monitoring:                    # optional — indexer stall detection
  #   indexer_stall_after: 5m
  #   notify: [ops]
  # server:                        # optional — HTTP hardening (auth/cors/bind)
  #   bind: 127.0.0.1:3940
  #   auth:
  #     token: "${{ secrets.RFLOW_API_TOKEN }}"
  #   cors:
  #     origins: ["https://ops.example.com"]
  #   health_public: true          # /health open for k8s probes (default)
  #   metrics_public: false        # /metrics follows auth (default)
  # retention:                     # optional — operator-driven history pruning
  #   live_runs: 180d              # succeeded/skipped runs older than this are prunable
  #   failed_runs: keep            # default keep (audit-first)
  #   replay_sessions: 14d
  #   test_runs: 30d
  #   approvals: keep
  #   archive_before_prune: true
  #   archive_path: ./archives
```

### port — optional

The single port rflow exposes, serving health/status. The embedded engines are
internal — rindexer's health server and rrelayer's API do **not** bind ports unless
you explicitly opt in via `relayer_api`.

### db\_connection — required

The Postgres connection string. Postgres is the only storage backend — there is no
other option, and no `storage:` block. One database holds three schemas:

| Schema     | Owner                                                                    |
| ---------- | ------------------------------------------------------------------------ |
| `rflow`    | workflow definitions mirror, run journal, cursors, relayer mappings, DLQ |
| `relayer`  | the embedded rrelayer                                                    |
| `rindexer` | the embedded rindexer                                                    |

The connection string is injected into both embedded engines, so you configure the
database exactly once. `rflow new` scaffolds a `docker-compose.yml` exposing Postgres
on `localhost:5448` with a matching `.env`:

```bash
DATABASE_URL=postgresql://postgres:rflow@localhost:5448/postgres
```

rflow also takes a per-project advisory lock on this database at boot, so two rflow
processes can never run the same project against the same database concurrently.

### max\_concurrent\_runs — optional

Maximum number of workflow runs executing at the same time across the project.
Within a [concurrency group](/workflows#concurrency), runs are always serialized
FIFO regardless of this value.

### relayer\_api — optional

Default: fully internal. Setting `relayer_api.enabled: true` deliberately exposes the
embedded rrelayer's REST API (rrelayer api-config passthrough: port, basic auth) —
your rflow project then doubles as an rrelayer server you can hit with the
[rrelayer SDKs](https://rrelayer.xyz).

| Field                     | Description                          |
| ------------------------- | ------------------------------------ |
| `enabled`                 | required bool                        |
| `port`                    | optional — port for the rrelayer API |
| `authentication_username` | optional — basic auth username       |
| `authentication_password` | optional — basic auth password       |

### ha — optional

Leader/standby high availability. A standby instance (`standby: true`, or the
`rflow start --standby` flag, which overrides the config) boots and then waits for
the per-project advisory lock instead of exiting; when the leader dies, Postgres
frees the session-scoped lock and the standby takes over within `takeover_poll`
(default `5s`), running the normal recovery-first boot. See
[Self-hosting → High availability](/self-hosting#high-availability-leaderstandby).

| Field           | Description                                           |
| --------------- | ----------------------------------------------------- |
| `standby`       | boot as a standby (default `false`)                   |
| `takeover_poll` | how often a standby re-probes the lock (default `5s`) |

### monitoring — optional

[Indexer stall detection](/operations/unattended-ops#indexer-stall-detection):
alert when the chain head advances but every event-trigger cursor on a
network is frozen past the window. Lazy — no monitor task runs unless this
block (or some workflow's `liveness:`) is declared.

| Field                 | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| `indexer_stall_after` | frozen-cursor window before a stall alert (default `5m`)                                        |
| `notify`              | [notification channel(s)](/config/notifications) to page (PagerDuty `critical` / Opsgenie `P1`) |

### server — optional

Production hardening of rflow's single exposed port. **Absent = today's
zero-config behaviour**: bind `0.0.0.0:<port>`, no authentication, no CORS, and
the viewer `/`, `/api/*`, `/metrics` and `/health` all open. rflow's port is a
localhost/private-network operator tool by default — set this block to expose it
safely inside private infrastructure.

```yaml
config:
  server:
    bind: 127.0.0.1:3940
    auth:
      token: "${{ secrets.RFLOW_API_TOKEN }}"
    cors:
      origins: ["https://ops.example.com"]
```

| Field            | Description                                                                                                                                                                                                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bind`           | `host:port` the server binds, overriding `port` and the default `0.0.0.0` host (e.g. `127.0.0.1:3940` to keep it on loopback behind a proxy). A non `host:port` value is a validation error.                                                                                                           |
| `auth.token`     | Shared bearer token — usually a `${{ secrets.<name> }}` expression. When set, the viewer `/` and `/api/*` require `Authorization: Bearer <token>`.                                                                                                                                                     |
| `cors.origins`   | Allowed browser origins for `Access-Control-Allow-Origin` + OPTIONS preflight. Each entry must be `*` or a `scheme://host[:port]` origin (no trailing slash or path, matching the browser's `Origin` header) — anything else is a validation error, and an empty list warns. Default: no CORS headers. |
| `health_public`  | Keep `/health` open even when auth is on (k8s probes carry no bearer). Default `true`.                                                                                                                                                                                                                 |
| `metrics_public` | Leave `/metrics` open for Prometheus even when auth is on. Default `false` — `/metrics` follows auth.                                                                                                                                                                                                  |

**Bearer auth** does a constant-time compare of the presented token against the
resolved config token OR any non-revoked [named token](#named-api-tokens). A
missing or bad token gets `401` with a `WWW-Authenticate: Bearer` header.
`/hooks/*` webhook routes are **never** covered by bearer auth — they keep their
own per-trigger [HMAC `auth:`](/workflows/triggers/webhook).

#### Named API tokens

Mint additional tokens without putting a shared secret in `rflow.yaml`, and
revoke a leaked one without a restart. These commands need only
`config.db_connection`, not a running server:

```bash
rflow token create --name ops-viewer   # prints the plaintext ONCE, stores only its hash
rflow token revoke <id>                 # auth stops accepting it immediately
rflow token ls                          # id / name / created / revoked — never the token
```

Only the hex SHA-256 of a token is stored (`rflow.api_tokens.token_hash`); the
plaintext is shown once at creation and never persisted or logged. Auth accepts
the config shared token **and** any non-revoked named token, so you can rotate
tokens per operator/dashboard independently of the yaml.

For Kubernetes, the [Helm chart](/self-hosting) mounts the token from a Secret
(`apiToken.enabled`).

### retention — optional

Operator-driven history pruning + archive. **Absent = nothing is ever
auto-pruned** (the backwards-compat default — rflow never deletes run history
behind your back). Every window is a duration or the literal `keep`, and every
field defaults to `keep`/off.

```yaml
config:
  retention:
    live_runs: 180d          # succeeded/skipped runs older than this are prunable
    failed_runs: keep        # failed/dead_letter — default keep (audit-first)
    replay_sessions: 14d     # disposable `rflow replay` sessions
    test_runs: 30d           # disposable `rflow test` sessions
    approvals: keep          # decided approval rows — default keep
    archive_before_prune: true
    archive_path: ./archives
```

Retention only ever runs when an operator invokes
[`rflow retention prune --yes`](/operations/retention-and-archive) — there is no
background pruner and no delete at boot. Active runs, pending approvals, parked
waits/delays, in-flight sends and running reorg responses are **never** prunable.
See [Retention & archive](/operations/retention-and-archive) for the full model,
the plan/prune commands and the redacted [`rflow archive
export`](/operations/retention-and-archive#rflow-archive-export).


## constants, secrets & lists

Three ways to get values into your expressions.

### constants

Static values, addressable as `${{ constants.<name> }}`:

```yaml
constants:
  scale_bps: "2500"
  treasury: "0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326"
```

```yaml
args: ["${{ mul_div(trigger.args.amount0, constants.scale_bps, 10000) }}"]
```

### secrets

Like constants, but **log-redacted**: anything under `secrets:` never appears in
rflow's logs or journal output. Addressable as `${{ secrets.<name> }}`.

```yaml
secrets:
  HOOK_KEY: ${BACKEND_HMAC_KEY}
```

Note the two layers here: `${BACKEND_HMAC_KEY}` is plain environment substitution at
load time; `${{ secrets.HOOK_KEY }}` is the expression that reads it at run time.
The typical consumers are an [http\_call](/workflows/steps/http-call) HMAC and a
[webhook trigger](/workflows/triggers/webhook)'s inbound verification:

```yaml
- id: notify-backend
  http_call:
    url: ${BACKEND_URL}
    hmac: "${{ secrets.HOOK_KEY }}"
    body: { tx: "${{ trigger.tx_hash }}" }
```

#### from — external secret providers

Instead of a `${VAR}` string, a secret's value may be a `from:` reference that
rflow fetches from **AWS Secrets Manager** or **GCP Secret Manager** at boot —
so production API keys never live in `.env` or the config file:

```yaml
secret_providers:
  aws-prod:
    aws_secrets_manager:
      region: eu-west-1
      prefix: /rflow/prod/

secrets:
  PRICE_API_KEY:
    from:
      provider: aws-prod
      key: price-api-key
  HOOK_KEY: ${BACKEND_HMAC_KEY}   # both forms coexist
```

Resolution is **fail-closed** (a missing/denied secret aborts the boot with the
provider + key named) and a fetched value redacts **identically** to a declared
one, everywhere. `.env` stays the zero-config default — a project with no
`secret_providers:` behaves exactly as before. Full provider config, IAM
pointers and the `rflow secrets ls|doctor` commands:
[external secret providers](/config/secret-providers).

### lists

Runtime-mutable watchlists, backed by Postgres. Seed them in YAML and use them with
the `in` operator:

```yaml
lists:
  watched_traders:
    seed: ["0xWhale1...", "0xWhale2..."]
```

```yaml
trigger:
  event:
    contract: AnyPool
    name: Swap
    network: ethereum
    where: "${{ trigger.args.sender in lists.watched_traders }}"
```

Membership checks against address lists are case-insensitive — see
[address semantics](/workflows/expressions#addresses-are-case-insensitive).

| Field    | Description                                                                |
| -------- | -------------------------------------------------------------------------- |
| `seed`   | Initial members, owned by the YAML                                         |
| `source` | Refresh members from `http:` / `sql:` / `file:` on an interval — see below |

A list's effective membership is the **union** of the seed, runtime members
(written by [`rflow list add`](/cli#rflow-list) and
[`list_add:` / `list_remove:` steps](/workflows/steps/state-and-lists#list_add--list_remove)),
and source-refreshed members. `rflow list show` breaks members down by
provenance. Mutations are visible to the very next `where:` evaluation.

#### source — http / sql / file

```yaml
lists:
  watched_traders:
    seed: ["0xWhale1..."]
    source:
      http:
        url: https://api.example.com/traders
        json_path: "$.data[*].address"   # default $ — the body is already an array
        refresh: 5m                      # default 5m

  vip_vaults:
    source:
      sql: "SELECT address FROM analytics.vip_vaults"   # single read-only SELECT, same Postgres

  blocked:
    source:
      file: ./blocked.txt               # newline-separated, # comments skipped
```

A refresh atomically replaces **only** the source-tagged rows — seed, manual and
workflow members survive every refresh. Values are trimmed, deduplicated and
address-shaped entries lowercased.

:::warning
Source feeds are checked **at refresh time, not by `rflow validate`** — a bad
`json_path`, a non-SELECT `sql:`, or an unreachable url logs loudly and keeps
the previous members (a broken feed never silently empties a watchlist). The
`sql:` source runs as a single read-only SELECT against rflow's own Postgres.
:::


## contracts

A **global registry** — every contract declared here is usable from any workflow,
trigger, or step by name.

```yaml
contracts:
  USDC:
    abi: ./abis/erc20.json
    addresses:                       # per-network map
      ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
      base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

  Treasury:
    abi: ./abis/treasury.json
    network: ethereum                # single-network shorthand
    address: "0xDep..."

  AnyPool:
    abi: ./abis/univ3-pool.json
    factory:                         # every child the factory ever deployed
      contract: UniV3Factory
      event: PoolCreated
      network: ethereum
```

| Field                 | Description                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `abi`                 | ✅ Path to the ABI json file, relative to the project directory — [`rflow abi fetch`](/config/abis) downloads the verified one for you |
| `addresses`           | Per-network map: `network → address` (or a list of addresses)                                                                         |
| `network` + `address` | Single-network shorthand; `address` also accepts a list                                                                               |
| `factory`             | Factory tracking — match every child deployed by a factory                                                                            |
| `index_events`        | Index these events for [`query:`](/workflows/steps/query) WITHOUT firing any workflow — see below                                     |

Use exactly one address form (`addresses`, `network`/`address`, or `factory`) —
validation checks this and that every referenced network exists.

### index\_events — index-only analytics

`index_events:` indexes a contract's events into Postgres **without any
workflow firing** — the historical dataset for
[`query:` steps](/workflows/steps/query) and the
[query trigger](/workflows/triggers/query):

```yaml
contracts:
  USDC:
    abi: ./abis/erc20.json
    network: ethereum
    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    index_events: [Transfer, Approval]
```

Rows land in `rflow_indexer_rflow_idx_<contract>.<event>`
(`rflow_indexer_rflow_idx_usdc.transfer` here — run
[`rflow tables`](/cli#rflow-tables) to see the live catalog). No runs, no
claims, no cursors in the run journal — indexing only.

Honest limits:

* Indexing starts at the **current head** when `rflow start` boots the
  indexer — there is no per-contract backfill knob yet. For deep history,
  point an event-trigger workflow (which owns `start_block` semantics) at
  the contract instead.
* `index_events` on a `factory:`-tracked contract is not supported yet —
  `rflow validate` (and boot) errors.
* Each event name must exist in the contract's ABI (validated); declaring an
  event some workflow also triggers on is fine but flagged as a warning —
  the rows are stored twice (once per table-naming family).

### Factory tracking

`factory:` scopes a contract to **every child a factory ever deployed** — past and
future. The classic use is DEX pools:

```yaml
contracts:
  UniV3Factory:
    abi: ./abis/univ3-factory.json
    network: ethereum
    address: "0x1F98431c8aD98523631AE4a59f267346ea31F984"
  AnyPool:
    abi: ./abis/univ3-pool.json
    factory: { contract: UniV3Factory, event: PoolCreated, network: ethereum }
```

An [event trigger](/workflows/triggers/event) on `AnyPool` fires for a `Swap` in
*any* pool, including pools created after rflow started.

| Field      | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `contract` | ✅ Name of the factory contract in this registry            |
| `event`    | ✅ The deployment event on the factory (e.g. `PoolCreated`) |
| `network`  | ✅ Network to track the factory on                          |

### Using registry entries

* Event triggers: `trigger: { event: { contract: USDC, name: Transfer, ... } }`
* Read steps: `read: { contract: USDC, function: "balanceOf(address)", ... }`
* Send steps: `send_transaction: { contract: USDC, function: "transfer(address,uint256)", ... }`
* Expressions: `${{ contracts.Treasury.address }}`

Send steps may also target a raw `to: "0x..."` address without a registry entry —
the registry is for contracts you reference more than once or need ABIs for.


## rflow\.yaml

One file defines the whole project. Everything below `rflow_version`, `name`,
`config` and `workflows` is optional — no signer is needed to monitor, no networks
are needed for cron + HTTP automations.

```yaml
rflow_version: 1          # config language version — only 1 is valid today
name: my-project

config: { ... }           # engine settings: port, db_connection, concurrency, HA
networks: [ ... ]         # one list feeds BOTH embedded engines
signer: { ... }           # global signing provider (rrelayer schema, 9 providers)
relayers: { ... }         # named wallets, created + cloned automatically
contracts: { ... }        # global ABI/address registry
constants: { ... }        # static values for expressions
secrets: { ... }          # log-redacted values for expressions
lists: { ... }            # runtime-mutable watchlists (Postgres-backed)
notifications: { ... }    # named channels (telegram/slack/discord/pagerduty/opsgenie/twilio)
workflows: { ... }        # the automations themselves
profiles: { ... }         # per-environment overlays (--profile <name>)
```

### Rules

* **Maps are keyed by name** — `workflows`, `relayers`, `contracts`, `lists` and
  notification channels are maps, and the key is the identity.
* **Strict validation** — an unknown key anywhere is a hard error. `rflow validate`
  collects *all* errors before reporting instead of stopping at the first.
* **Definition vs state** — the YAML is the definition; runtime state (pause flags,
  cursors, run history) lives in Postgres and survives edits and restarts.
* **Environment substitution** — `${VAR}` anywhere in the file is replaced from the
  environment (a `.env` in the project directory is loaded automatically). Secrets
  are never written to disk by rflow.
* **One expression language everywhere** — `${{ ... }}` works in conditions and
  values alike. See [Expressions](/workflows/expressions).

### Pages

* [config](/config/config) — port, db\_connection, max\_concurrent\_runs, relayer\_api, ha
* [networks](/config/networks) — chains + every indexer/relayer passthrough
* [signer](/config/signer) — the 9 signing providers, per-network overrides
* [relayers](/config/relayers) — named wallets, lifecycle, per-relayer policies
* [contracts](/config/contracts) — registry, addresses, factory tracking
* [constants, secrets & lists](/config/constants-secrets-lists) — including http/sql/file list sources
* [notifications](/config/notifications) — telegram, slack, discord, pagerduty, opsgenie, twilio
* [profiles & editor setup](/config/profiles) — per-environment overrides, JSON Schema autocomplete
* [workflows](/workflows) — triggers, steps, control flow, expressions

:::tip
Add `# yaml-language-server: $schema=https://rflow.xyz/rflow.schema.json` as the
first line of `rflow.yaml` for editor completion and validation — see
[editor setup](/config/profiles#editor-autocomplete-for-rflowyaml).
:::


## networks

One `networks:` list feeds **both** embedded engines — indexer settings and relayer
settings live side by side on the same entry. Optional: pure off-chain projects
(cron → HTTP → notify) declare no networks and neither engine boots.

```yaml
networks:
  - name: ethereum
    chain_id: 1
    rpc: [${ETH_RPC}, ${ETH_RPC_FALLBACK}]   # one url or a list of fallbacks
    ws: ${ETH_WS}                            # RESERVED - parsed but not wired yet (validate warns)
    confirmations: 12                        # relayer CONFIRMED depth (default 12)
  - name: base
    chain_id: 8453
    rpc: ${BASE_RPC}
```

### Core fields

| Field              | Required | Description                                                                                                                                                                                                   |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | ✅        | Your label for the chain — referenced by contracts, triggers and steps                                                                                                                                        |
| `chain_id`         | ✅        | The EVM chain id                                                                                                                                                                                              |
| `rpc`              | ✅        | One provider url or a list (fallback order)                                                                                                                                                                   |
| `ws`               |          | **Reserved — not wired yet.** Parsed for forward compatibility, but neither engine consumes it today (head tracking stays HTTP polling; tune `block_poll_frequency` instead). `rflow validate` warns when set |
| `confirmations`    |          | Depth at which the relayer marks a tx CONFIRMED (default 12). Not to be confused with per-trigger [`confirmations`](/workflows/triggers/event#confirmations)                                                  |
| `signing_provider` |          | Per-network [signing provider override](/config/signer#per-network-override)                                                                                                                                  |

### rindexer passthroughs

All optional; passed verbatim to the embedded indexer (semantics documented at
[rindexer.xyz](https://rindexer.xyz)):

| Field                      | What it controls                                 |
| -------------------------- | ------------------------------------------------ |
| `block_poll_frequency`     | How often the indexer polls for new blocks       |
| `max_block_range`          | Max block span per `eth_getLogs` request         |
| `compute_units_per_second` | Rate limiting for CU-metered providers           |
| `get_logs_settings`        | Advanced log-fetch tuning                        |
| `multicall3_address`       | Override the Multicall3 address on exotic chains |
| `reorg_handling`           | rindexer reorg detection tuning                  |

### rrelayer passthroughs

All optional; passed verbatim to the embedded relayer (semantics documented at
[rrelayer.xyz](https://rrelayer.xyz/config/networks/config)):

| Field                      | What it controls                                                                   |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `gas_provider`             | Gas price oracle (fallback / blocknative / infura / tenderly / etherscan / custom) |
| `gas_bump_blocks_every`    | How many blocks before a pending tx's gas is bumped                                |
| `max_gas_price_multiplier` | Cap on gas escalation                                                              |
| `enable_sending_blobs`     | Allow EIP-4844 blob transactions                                                   |
| `permissions`              | Allowlists, `disable_native_transfer`, `disable_transactions`, ...                 |
| `api_keys`                 | Network-scoped API keys for the (opt-in) relayer API                               |
| `automatic_top_up`         | Relayers fund each other / from a Safe when balances run low                       |

Example top-up — the treasury relayer keeps every other relayer above 0.1 native:

```yaml
networks:
  - name: ethereum
    chain_id: 1
    rpc: ${ETH_RPC}
    automatic_top_up:
      - from:
          relayer:
            address: "${{ relayers.treasury.address }}"
            internal_only: true
        relayers: "*"
        native: { min_balance: "0.1", top_up_amount: "0.2" }
```

rflow validates these blocks when it generates the runtime engine configs at boot
(`.rflow/runtime/{rindexer,rrelayer}/`) — env placeholders are preserved, so secrets
never land on disk.


## notifications

Named channels that [notify steps](/workflows/steps/notify) send into. rflow ships
its own senders — no external webhook relays needed.

```yaml
notifications:
  channels:
    ops:
      telegram:
        bot_token: ${TG_BOT_TOKEN}
        chat_id: ${TG_CHAT_ID}
    eng:
      slack:
        webhook_url: ${SLACK_WEBHOOK}
    alerts:
      discord:
        webhook_url: ${DISCORD_WEBHOOK}
    pager:
      pagerduty:
        routing_key: ${PD_ROUTING_KEY}
    oncall:
      opsgenie:
        api_key: ${OPSGENIE_API_KEY}
        eu: true
    sms:
      twilio:
        account_sid: ${TWILIO_ACCOUNT_SID}
        auth_token: ${TWILIO_AUTH_TOKEN}
        from: "+15550001111"
        to: "+15552223333"
```

Each channel configures **exactly one** sender (validation error otherwise).

### telegram

| Field       | Description                                           |
| ----------- | ----------------------------------------------------- |
| `bot_token` | ✅ Bot token from [@BotFather](https://t.me/BotFather) |
| `chat_id`   | ✅ Target chat/group id                                |

### slack

| Field         | Description                                                           |
| ------------- | --------------------------------------------------------------------- |
| `webhook_url` | ✅ An [incoming webhook](https://api.slack.com/messaging/webhooks) url |

### discord

| Field         | Description             |
| ------------- | ----------------------- |
| `webhook_url` | ✅ A channel webhook url |

### pagerduty

Sends through the [Events API v2](https://developer.pagerduty.com/docs/events-api-v2-overview)
(`events.pagerduty.com/v2/enqueue`, `event_action: trigger`).

| Field         | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| `routing_key` | ✅ The integration (routing) key of an Events API v2 integration |

Severity follows what fired the notification: `notify:` steps send `error`,
[circuit breaker](/workflows#circuit_breaker) trips and
[liveness/stall breaches](/operations/unattended-ops#severity-mapping) send
`critical`, and [approval](/approvals) requests send `info`.

### opsgenie

Creates alerts via the [Alert API](https://docs.opsgenie.com/docs/alert-api)
(`Authorization: GenieKey <api_key>`).

| Field     | Description                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| `api_key` | ✅ An API integration key                                                     |
| `eu`      | Use the EU host `api.eu.opsgenie.com` (default `false` = `api.opsgenie.com`) |

Priority follows the same taxonomy as pagerduty severity: circuit trips and
[liveness/stall breaches](/operations/unattended-ops#severity-mapping) are
`P1`, `notify:` steps `P3`, approval requests `P5`.

### twilio

SMS through the Messages API (basic auth `account_sid:auth_token`).

| Field         | Description                                              |
| ------------- | -------------------------------------------------------- |
| `account_sid` | ✅ Account SID                                            |
| `auth_token`  | ✅ Auth token                                             |
| `from`        | ✅ The sending Twilio number (E.164, e.g. `+15550001111`) |
| `to`          | ✅ The destination number (E.164)                         |

### Using channels

```yaml
steps:
  - id: alert
    notify:
      channel: ops
      message: "large transfer: ${{ format_units(trigger.args.value, 6) }} USDC"
```

Messages are full templates — any [expression](/workflows/expressions) works, and
values under `secrets:` are redacted if they ever end up in one.


## profiles

Per-environment overrides selected at runtime with `--profile <name>` — one
`rflow.yaml`, many environments:

```yaml
networks:
  - name: ethereum
    chain_id: 1
    rpc: ${ETH_RPC}

constants:
  treasury: "0x1111111111111111111111111111111111111111"

profiles:
  staging:
    networks:                 # replaces `ethereum` by name
      - name: ethereum
        chain_id: 11155111
        rpc: ${SEPOLIA_RPC}
    constants:                # merged by key — profile wins
      treasury: "0x2222222222222222222222222222222222222222"
    config:
      port: 4000              # engine settings a profile may override
```

```bash
rflow validate --profile staging   # validates the MERGED view
rflow start --profile staging      # boots the MERGED view
```

### Merge semantics

Applied **after** `${VAR}` env substitution, **before** validation — so
`validate --profile` sees exactly what `start --profile` boots.

| Section     | Behaviour                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `networks`  | Replace-by-name: a profile network **replaces** the base network with the same name; new names are appended; unmentioned base networks are kept. |
| `constants` | Merged by key — the profile value wins, other base constants are kept.                                                                           |
| `config`    | Individual settings override (`port` today).                                                                                                     |

An unknown profile name is a hard error that lists what *is* available:

```
unknown profile 'production' - available profiles: local, staging
```

### Editor autocomplete for rflow\.yaml

rflow ships a JSON Schema for the whole config surface. Point
[yaml-language-server](https://github.com/redhat-developer/yaml-language-server)
(VS Code's YAML extension, Neovim's yamlls, ...) at it with a modeline at the
top of your `rflow.yaml`:

```yaml
# yaml-language-server: $schema=https://rflow.xyz/rflow.schema.json
rflow_version: 1
```

or generate it locally (it's also committed at
`documentation/docs/public/rflow.schema.json`):

```bash
rflow schema > rflow.schema.json
```

You get completion, hover docs and unknown-key/type squiggles for every
trigger, step and setting.


## relayers

Named wallets your workflows send transactions from. The names are **your labels** —
nothing about them is special, and you never touch a relayer API or manage the
name↔key mapping yourself.

```yaml
relayers:
  payout:
    networks: [ethereum, base]     # same address on all listed chains
    speed: FAST                    # SLOW | MEDIUM | FAST | SUPER
    policy:
      max_gas_price: 100 gwei      # abort sends when gas is above this
      whitelist_receivers:         # the only addresses this relayer may send to
        - "0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326"
  treasury:
    networks: [ethereum]
    import: { id: "b47c..." }      # adopt an existing relayer (see below)
```

| Field      | Required | Description                                                                                            |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `networks` | ✅        | Networks the relayer exists on — created on the first, cloned to the rest, **same address everywhere** |
| `speed`    |          | rrelayer transaction speed. Gas bumping/escalation is rrelayer's job                                   |
| `policy`   |          | Per-relayer guard rails, checked by rflow on every send from this relayer — see below                  |
| `import`   |          | Adopt an existing relayer by rrelayer uuid                                                             |

### policy — per-relayer guard rails

`policy.max_gas_price` (a wei literal, validated statically) and
`policy.whitelist_receivers` apply to **every send from this relayer**, whatever
workflow issues it.

:::warning
Policies are enforced by rflow **client-side, before queueing**: the gas cap is
checked against the current `eth_gasPrice` (a trip is
[`gas_cap_exceeded`, retryable](/workflows/steps/send-transaction#gas--client-side-guardrails)),
and `whitelist_receivers` checks the transaction's **final `to`** — for a
[`multicall:`](/workflows/steps/send-transaction#multicall--n-calls-one-transaction)
send that is the Multicall3 contract, and the error message says so. Nothing is
spliced into the embedded relayer's own config; for engine-level enforcement,
the network-level [`permissions` passthrough](/config/networks#rrelayer-passthroughs)
(keyed by relayer address) remains available and is enforced by rrelayer itself.
:::

### Lifecycle

Wallet creation is rflow's job and it is seamless:

1. You declare a [signing provider](/config/signer) (the key material) and named
   relayers (pure labels).
2. At first `rflow start` (or standalone via `rflow relayers sync`), rflow reconciles:
   each name missing from its mapping table is created through the embedded rrelayer
   admin client (rrelayer name `rflow/<name>`) on its first listed network, then
   **cloned** to the rest — clones reuse the wallet index, which is why the address
   is identical cross-chain.
3. The mapping `(name → relayer id per chain, address)` is persisted in the `rflow`
   schema — stable forever after.
4. First boot prints a funding table:

   ```
   payout → 0xAbc... on ethereum, base — fund me
   ```

   `rflow relayers ls` / `rflow relayers balance` show it any time, and
   [funding operations](#funding-operations) below cover estimating, funding and
   auditing balances. Ongoing funding can be automated with the
   [`automatic_top_up`](/config/networks#rrelayer-passthroughs) passthrough.

### Renames are handled honestly

The YAML key is the identity, so renaming it in the file would create a **new
wallet**. rflow detects the pattern — a previously-mapped name gone plus a new
unmapped name — and tells you before creating anything:

```
'payout' is unmapped; orphaned relayer 'hot' still holds funds at 0xAbc...
run `rflow relayers rename hot payout` to keep the wallet, or continue to create a fresh one.
```

`rflow relayers rename <old> <new>` re-labels the mapping without touching keys.
`rflow relayers ls` always shows every mapping including orphans, and removing a name
from the YAML never deletes a relayer — `rflow validate` warns about orphans instead.

### Importing existing rrelayer relayers

If you share an rrelayer database with other services (a standalone rrelayer, or
another rflow project on the same Postgres), adopt one of its relayers instead of
creating a fresh wallet. The guided flow is **discover → import → verify**:

```bash
rflow relayers discover                # list every relayer in the shared rrelayer db
rflow relayers import treasury --id b47c1e2a-... --network ethereum
rflow relayers import --interactive    # pick from discover, prompt for the name
rflow relayers verify-imports          # re-check every import (CI-friendly)
```

`discover` shows each relayer's uuid, address, network and a **signer-compatibility
check** — whether the [signing provider](/config/signer) you configured derives that
relayer's address. Only compatible relayers can be imported.

`import` writes the block into `rflow.yaml` through the same comment-preserving
editor as [`rflow add`](/cli#rflow-add) (your comments/ordering survive), refusing
to clobber an existing relayer of the same name:

```yaml
relayers:
  treasury:
    networks: [ethereum]
    import:
      id: "b47c1e2a-..."
```

The derived-address check runs **before anything is written** — a signer mismatch
refuses the import loudly, because otherwise every simulation would run as the old
wallet while the engine signs with a different key. The same verification runs
again at every boot (a mismatch is a boot error), and `rflow relayers
verify-imports` runs it standalone: a table of `ok / MISMATCH / NOT FOUND` per
import, exiting non-zero on any failure so CI can gate on it. `rflow doctor` also
checks each import's adoption state.

### Funding operations

Knowing every address is half the job — the other half is keeping them funded:

```bash
rflow relayers balance          # balances per chain with low-balance flags (--json)
rflow relayers funding-plan     # balance vs estimated need per relayer/network (--json)
rflow relayers qr payout        # the address + a terminal QR code to fund from a wallet
rflow relayers topup-plan       # which relayers are short, and by how much
rflow relayers topup --from treasury --to "*" --network ethereum --to-target --yes
rflow relayers history --since 30d   # recent gas spend + top-up actions
```

`funding-plan` estimates how much native each relayer wants:
**targeting money workflows × sends-of-headroom × safety factor × live gas price ×
typical gas** (defaults 50 sends, 3×, 150k gas — all overridable with
`--sends-per-workflow` / `--safety-factor` / `--typical-gas`). This is an honest
gas-headroom heuristic, not a value forecast: transfer *values* are unknowable
statically, so the safety factor is the coarse knob covering them. A relayer no
money workflow targets needs nothing and is never flagged.

`topup` funds shortfalls from a funding relayer as **normal relayer sends**: the
plan prints first, `--yes` is required to broadcast, and the command refuses when
the funding relayer is itself underfunded or cannot cover the total. Every top-up
lands in the [native spend ledger](/operations/spend-tracking) (visible in
`rflow spend` and the explorer) plus an `rflow.operator_audit` row, so
`rflow relayers history` shows who topped up whom.

For *automated* funding, the [`automatic_top_up`](/config/networks#rrelayer-passthroughs)
network passthrough lets rrelayer itself top relayers up from a funding relayer or
Safe — the `relayer-underfunded` [lint rule](/operations/lint-and-ci#relayer-underfunded)
nudges money-moving projects toward it, and `rflow doctor` warns live when a
relayer's balance drops below the funding-plan estimate. The explorer's
**Relayers** view (backed by `GET /api/relayers`) shows the same address book:
balances, low-balance flags, funding estimates and recent spend.

### Using relayers

* Send steps reference them by name: `send_transaction: { relayer: payout, ... }`
* Expressions can read the address: `${{ relayers.payout.address }}`
* Workflows can be restricted to specific relayers via
  [`permissions`](/workflows#permissions)


## external secret providers

Fetch [`secrets:`](/config/constants-secrets-lists#secrets) values from **AWS
Secrets Manager** or **GCP Secret Manager** at boot, so production API keys,
webhook HMAC keys and notification tokens never live in `.env` or a mounted
file. Optional: **`.env` stays the zero-config default** — a project with no
`secret_providers:` behaves exactly as before, and both forms coexist in one
`secrets:` map.

```yaml
secret_providers:
  aws-prod:
    aws_secrets_manager:
      region: eu-west-1
      prefix: /rflow/prod/

secrets:
  PRICE_API_KEY:
    from:
      provider: aws-prod
      key: price-api-key      # fetches /rflow/prod/price-api-key
  HOOK_KEY: ${BACKEND_HMAC_KEY}   # the plain env form still works
```

Anywhere a secret is used, nothing changes: `${{ secrets.PRICE_API_KEY }}` in
steps, triggers and `config.server.auth.token` reads the fetched value exactly
like an env-sourced one.

### The providers

Exactly **one provider kind** per entry (validation error otherwise). Neither
carries static credentials in `rflow.yaml` — auth is ambient, mirroring the
[signer's cloud providers](/config/signer).

#### aws\_secrets\_manager

```yaml
secret_providers:
  aws-prod:
    aws_secrets_manager:
      region: eu-west-1
      prefix: /rflow/prod/           # optional — prepended to every from.key
      # endpoint_url: http://localhost:4566   # optional — LocalStack / VPC endpoint
```

Fetches with `GetSecretValue` using the **AWS default credential chain** (env
vars, shared profile, IMDS/IRSA role). The remote secret must hold a **string**
value (binary secrets are not supported). Grant the runtime identity
`secretsmanager:GetSecretValue` on the secrets under your prefix — see the
[AWS IAM docs](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html)
(rflow reads secrets; it never manages IAM).

#### gcp\_secret\_manager

```yaml
secret_providers:
  gcp-prod:
    gcp_secret_manager:
      project: my-project
      # service_account_key_path: ./gcp-sa.json   # optional — default: Application Default Credentials
      # prefix: rflow-prod-                       # optional — prepended to every from.key
      # version: latest                           # optional — default latest
```

Fetches with `accessSecretVersion`. Auth is a **service-account key file**
(path relative to the project dir) when `service_account_key_path` is set,
otherwise **Application Default Credentials** (`GOOGLE_APPLICATION_CREDENTIALS`,
a `gcloud auth application-default login`, or the metadata server). Grant the
identity `roles/secretmanager.secretAccessor` — see the
[GCP access control docs](https://cloud.google.com/secret-manager/docs/access-control).

### The from: form

Each provider-backed secret names its provider and the remote key:

```yaml
secrets:
  PRICE_API_KEY:
    from:
      provider: aws-prod     # a secret_providers: entry (typo = validation error)
      key: price-api-key     # the remote secret name (provider prefix prepended)
```

### Fail-closed resolution

Providers resolve **once, at boot** (`rflow start`, before validation-dependent
work runs). A missing, denied or unreachable secret is a **hard error naming
the provider and key** — never a silent empty value — and every failure is
reported in one message:

```
failed to resolve 2 secret(s) from `secret_providers:` (rflow fails closed - no secret is left empty):
  - secret 'PRICE_API_KEY': provider 'aws-prod' key 'price-api-key' access was denied (AccessDeniedException: ...)
  - secret 'HOOK_KEY': provider 'aws-prod' key 'webhook-hmac' was not found (no such secret)
```

Values are fetched at boot only — rotating a remote secret takes effect on the
next boot (`rflow start`, or a `start --watch` reload, which re-runs the full
boot). A background refresh-on-interval is a possible future nicety, not
implemented today.

The same fail-closed resolve also runs in every CLI command that renders or
redacts secrets in-process: `rflow test`, `replay` and `command test` (they
render `${{ secrets.* }}`), and the journal read paths — `history`, `runs
show`/`export` and `archive` — whose scrubber can only strip a
provider-fetched value it actually holds. If the provider is unreachable,
those commands error rather than print journal output the scrubber could not
fully redact. Commands that never touch secret values (`ls`, `status`,
`spend`, …) skip resolution entirely.

### Redaction guarantee

A provider-fetched value is redacted **identically** to a `${VAR}`-sourced one,
in every surface: the journal, run history and its JSON/CSV exports, the
`/api/*` responses, archive exports, CLI output, and notify/approval messages
(`[redacted:<name>]`). The [config version](/operations/versioning-and-plan)
snapshot and hash treat it as a redacted secret value — the fetched plaintext
never lands in `rflow.config_versions`, and rotating the remote value never
mints a new version.

### secrets ls / doctor

```bash
rflow secrets ls        # name / source (env | provider:<name>) / remote key / resolved? / version — never values
rflow secrets doctor    # fetch-check every provider secret; exit non-zero on any failure
```

`doctor` reports `ok` / denied / not-found per secret **without printing
values** and exits non-zero on any failure — the CI-friendly way to verify IAM
before a deploy. The same per-secret checks run inside
[`rflow doctor`](/operations/doctor-and-explain)'s deep suite whenever a
project declares provider-backed secrets (unlike the signer's cloud providers,
a Secret Manager read is side-effect-free, so doctor checks it live).

### Non-goals

rflow is not a secret manager: it never writes or rotates remote secrets, never
manages IAM policies, and never shows raw values. Signing-key material stays
with the [signer providers](/config/signer) (rrelayer's own AWS/GCP/KMS
support) — `secret_providers:` is for workflow configuration secrets.


## signer

The signing provider — the key material your [relayers](/config/relayers) derive
wallets from. Exact rrelayer `signing_providers` schema, all 9 providers. Optional:
monitoring-only projects declare no signer and the relayer engine never boots.

**Exactly one provider** must be set (validation error otherwise).

```yaml
signer:
  aws_kms:
    region: eu-west-1
```

### The 9 providers

Field-level semantics are rrelayer's — see the
[rrelayer signing provider docs](https://rrelayer.xyz/config/signing-providers/aws-kms)
for provider setup guides.

#### raw — dev only

```yaml
signer:
  raw:
    mnemonic: ${RAW_DANGEROUS_MNEMONIC}
```

A plain mnemonic. Fine for anvil and testnets; the env var name says the rest.

#### private\_keys

```yaml
signer:
  private_keys: [${PK_0}, ${PK_1}]
```

#### aws\_kms

```yaml
signer:
  aws_kms:
    region: eu-west-1
    # endpoint_url, multi_region, danger_override_alias — optional
```

#### aws\_secret\_manager

```yaml
signer:
  aws_secret_manager: { id: my-secret, key: mnemonic, region: eu-west-1 }
```

#### gcp\_secret\_manager

```yaml
signer:
  gcp_secret_manager:
    id: my-secret
    key: mnemonic
    service_account_key_path: ./gcp-sa.json
    # version — optional
```

#### privy

```yaml
signer:
  privy: { app_id: ${PRIVY_APP_ID}, app_secret: ${PRIVY_APP_SECRET} }
```

#### turnkey

```yaml
signer:
  turnkey:
    api_public_key: ${TURNKEY_PUB}
    api_private_key: ${TURNKEY_PRIV}
    organization_id: ${TURNKEY_ORG}
    wallet_id: ${TURNKEY_WALLET}
```

#### fireblocks

```yaml
signer:
  fireblocks:
    api_key: ${FIREBLOCKS_API_KEY}
    private_key_path: ./fireblocks.pem
    identity: my-vault
    # sandbox, hidden_on_ui — optional
```

#### pkcs11 — hardware modules (beta)

```yaml
signer:
  pkcs11:
    library_path: /usr/lib/softhsm/libsofthsm2.so
    identity: rflow
    # pin, slot_id, test_mode — optional
```

### Per-network override

Any network can override the global signer — e.g. KMS on mainnet, a raw mnemonic on a
testnet:

```yaml
signer:
  aws_kms: { region: eu-west-1 }

networks:
  - name: ethereum
    chain_id: 1
    rpc: ${ETH_RPC}
  - name: sepolia
    chain_id: 11155111
    rpc: ${SEPOLIA_RPC}
    signing_provider:
      raw: { mnemonic: ${TEST_MNEMONIC} }
```

:::warning
A relayer keeps the **same address on every network it is cloned to** because the
wallet index maps into one signing provider. If two networks use different signing
providers, relayers spanning both cannot share an address — keep cross-chain relayers
on networks with the same provider.
:::

### How keys map to relayers

One signing provider yields many wallets by **wallet index** (mnemonic index 0, 1,
2… / KMS key n). When rflow creates a relayer, rrelayer assigns the next free index
and persists it — that index *is* the name↔key mapping. See the
[relayer lifecycle](/config/relayers#lifecycle).