Configuration Reference

The keeper reads one YAML file, bazaar-keeper.yaml by default (-c <path> names another). This page lists every section and every key, with its type, its default and what it does. Defaults are the schema’s (packages/keeper/src/config/schema.ts): a key you leave out takes its default, and so does a whole section.

bazaar keeper init writes a working file for you (Setting Up a Keeper); the repository’s bazaar-keeper.example.yaml shows the common options with comments. A complete annotated example is at the end of this page.

How the File Is Read

1. The .env file in the config’s directory is loaded into the environment. Variables already set in the environment win.
2. The YAML is parsed. It must be a mapping.
3. The secrets rules are checked on the text as written: secret keys must be ${NAME} references, URLs that may carry a key must come from the environment, and prices.headers values must be references.
4. Every ${NAME} and ${NAME:-default} in a string value is filled from the environment.
5. The result is validated against the schema. Unknown keys are refused everywhere, so a typo is an error, not a silently ignored setting. Every problem is listed at once:

the config is not valid:
  rpc: Unrecognized key(s) in object: 'chunk'
  wallets.default: a keystore wallet needs path
  config: job liquidation uses wallet 'fast', which is not under wallets

The library’s parseConfig(object) does step 5 only (The Keeper as a Library).

Three YAML details matter here:

• Quote addresses. YAML reads an unquoted 0x… as a hexadecimal number. Write factory: "0x3Aa5ebB10DC797CAC828524e59A333d0A371443c".
• An empty job turns it off. liquidation: with nothing under it is null, and a null job is disabled. Write liquidation: {} to enable a job with its defaults.
• Use block style for references. ${NAME} inside a flow mapping ({ botToken: ${TG_BOT_TOKEN} }) does not parse; write the mapping on separate lines, or quote the value.

Where

The keeper reads everything else from the factory: the lens, the terminator, the oracle, USDC, every market and its price feeds. It refuses to start if the lens or the terminator belongs to a different factory. A factory that is not a network’s official one is used all the same, with a warning (factory 0x… is not an official deployment) in the log, doctor and status.

startBlock left out. Nothing of Bazaar’s emits a log before its factory exists, so the scan can start at the factory’s deployment block. When startBlock is left out (and no official preset gives it), a first start without a subgraph finds that block on chain: a binary search on eth_getCode at historical blocks, about 30 reads on Arbitrum One. It logs found the factory's deployment block, N (set startBlock: N in the config to skip the search). The search needs an RPC that keeps historical state (hosted providers do). A node that has pruned it cannot answer, and the keeper refuses to start rather than scan from block 0:

could not find the factory's deployment block (…). Set startBlock in the config to the block the factory was deployed in, use an RPC that keeps historical state, or configure a subgraph

startBlock matters only for the first start without a subgraph (or after the state directory is emptied): later starts resume from the snapshot.

rpc

The node must support eth_call state overrides for rewards to be measured (What the Keeper Does). A log range it refuses (too many blocks or logs) is halved and asked for again, down to one block, and widened again after eight successes in a row; a lower logChunk avoids the refused requests. Rate-limit answers (HTTP 429), timeouts and connection failures are not refusals: the sync step fails and the next tick resumes after the last chunk applied.

subgraph

The subgraph only finds accounts and orders for the first start: the keeper reads its _meta block, pages through open positions and live or bounty-holding orders pinned to that block, and tails the chain’s logs from the next block. Every decision is made from chain state. If the subgraph fails for any reason, the first start indexes from chain logs instead. The opportunities scan also uses it to find open termination claims, insurer votes and listings.

prices

Prices come from Pyth Pro: signed updates the keeper attaches to its calls and the pair’s oracle has verified on chain. Pyth Pro needs an access token, which you get from Pyth.

The endpoint. pyth is three stream endpoints (wss://pyth-lazer-0.dourolabs.app/v1/stream, and -1 and -2), the request API at https://pyth-lazer.dourolabs.app and the symbols registry at https://pyth.dourolabs.app. A base URL names a service that answers the request API and the symbols registry at that URL and streams at its /v1/stream over ws or wss: http://127.0.0.1:8787 (where bazaar mock-prices listens) means the request API and the registry there and the stream at ws://127.0.0.1:8787/v1/stream. streamUrls, restUrl and symbolsUrl each replace one of the three, over a preset or a base URL. A URL that carries a key is a secret like any other: write it as ${NAME} (the secrets rules).

Plain http and ws. A token or a header sent over plain http or ws can be read by anyone on the path, so the keeper refuses to start when one would go that way to another machine: prices: the price request URL uses http://, which would send the price token and headers unencrypted to another machine: …. The same holds for a user name, a password or a query inside a URL, token or no token (prices: a price stream URL holds a user name, a password or a query and uses ws://, …); no message quotes the URL. Use https and wss. Set allowInsecure: true only for an endpoint on a network you trust end to end (a proxy beside the keeper, say). This machine is exactly localhost, an address in 127.0.0.0/8, or [::1]: a name under .localhost is resolved like any other name, so it counts as another machine. bazaar mock-prices on the same machine needs neither a token nor this.

A compatible service must serve POST /v1/latest_price, POST /v1/price (the one-second channel’s update for a past second, which terminate-scheduled settles with), GET /v1/symbols (feed symbols, for market labels; asked without the token) and the WebSocket stream.

The stream. Updates are judged against the chain’s clock, as their prices are: one stamped more than a minute ahead of it drops the endpoint that sent it. The keeper opens one subscription per watched market, for that market’s feeds together, plus one for ETH/USD (Pyth Pro feed 2, for pricing gas). The signed update a call attaches therefore carries exactly its pair’s feeds, both legs of a composite in one update, and costs one verification fee. The same subscriptions run on every stream endpoint and each update is taken once, from whichever endpoint brings it first; an endpoint that drops is reconnected while the others keep delivering. Three failures in a row mark prices unhealthy and switch a stream to polling for a minute. Each newer print wakes the liquidation and trigger planners. The stream runs on the ws package, on every supported Node version, bounded so an endpoint cannot make the keeper buffer more than it reads: no compression, no redirects, a 10 s handshake timeout, and a frame larger than 3 MiB ends the connection unread (the endpoint is reconnected like any that drops).

The channel. A faster channel shows a move sooner and brings more updates to read. A print is as old as its price, not as the update that carries it: a quiet feed’s updates carry its last price forward, and those read as stale. A feed Pyth does not serve on the chosen channel, or that the token does not cover, gets no print; the keeper warns once per feed and its markets get no price.

checkSigners. Once the deployment is read, the keeper asks its Pyth verifier whether it trusts the signer of each update (isValidSigner, each answer kept for a minute) and takes no price from an update signed by anyone else: a stream endpoint that sends one is dropped and reconnected while the others keep delivering, and a request API response that carries one is refused whole. The chain verifies every update a call carries either way; the ETH/USD print that prices gas reaches no contract, so this is the only check on it, and with it off the keeper warns at start (bazaar keeper doctor says so too). It costs one signature recovery per update taken, which adds up with many markets on a fast channel: turn it off, or pick a slower channel, if the keeper falls behind the stream.

wallets

A map from a name of your choosing to a wallet. Jobs use default unless they name another. Left out, the keeper is watch-only. Wallets & Secrets explains each type.

jobs

Each job is switched on by being present (liquidation: {} or with settings), and off by being left out, null, or enabled: false. Every job takes the common keys; most also have their own. The Jobs explains what each one does with them.

Common Keys

Naming markets. An address names one market and must be one of the factory’s (0x… is not a market of this factory). A label such as BTC/USD names every market carrying it: labels are not unique, since a market relisted after a termination keeps its label and a composite is labelled after its base. Such a label covers all of them, each job acting only on those in a market state it runs in, and the keeper logs a warning naming their addresses. A name no market carries stops the start with no market called 'X'. Markets: …. bazaar keeper markets lists every market with its label and address.

liquidation

triggers

unload

adl

refresh

terminalSettlement

collect

sweepExpired

profit

Each job can override both. Budgets & Losing Calls.

gas

budget

Budgets & Losing Calls explains how they combine.

safety

A revert on chain means the state changed between the simulation and the block (usually another keeper got there first). A success resets the count.

alerts

Running in Production describes each kind.

state

So one state directory can hold several keepers (different networks or factories) side by side. init sets it to state/ beside the config.

log

engine

A Complete Example

Every section, with the defaults written out where they are worth seeing. Secrets come from .env beside the file.

# ---- Where ----
network: arbitrum-one
factory: "0x0000000000000000000000000000000000000000"  # quoted: YAML reads bare 0x… as a number
startBlock: 123456789            # the factory's deployment block; leave out to have it found on chain

rpc:
  http: ${RPC_HTTP_URL}          # the provider's URL holds its key: it lives in .env
  send: sequencer                # Arbitrum One: submit straight to the sequencer
  maxRequestsPerSecond: 25
  logChunk: 2000                 # blocks per eth_getLogs; refused ranges are halved automatically

subgraph:
  url: ${SUBGRAPH_URL:-none}     # a Bazaar subgraph if SUBGRAPH_URL is set, else index from logs

prices:
  endpoint: pyth                 # Pyth Pro; or ${PRICE_ENDPOINT_URL} for another Pyth Pro compatible service
  token: ${PYTH_PRO_TOKEN}       # your Pyth Pro access token
  channel: fixed_rate@200ms
  checkSigners: true             # only updates signed by a signer the deployment's Pyth verifier trusts
  stream: true
  streamIdleTimeoutSeconds: 10
  sendMarginSeconds: 1.0

# ---- Who ----
wallets:
  default:                       # collect, refresh, unload, settlement, manual operations
    type: keystore
    path: /srv/keeper/keys/default.json
    password: ${KEEPER_KEYSTORE_PASSWORD}
  fast:                          # its own nonce queue for the jobs that race
    type: keystore
    path: /srv/keeper/keys/fast.json
    password: ${KEEPER_FAST_PASSWORD}

# ---- What ----
jobs:
  liquidation:
    wallet: fast
    markets: all
    allowLoss: true              # liquidate even at a small loss: it keeps the market solvent
    maxLossUsdPerCall: 0.10
    lossBudgetUsdPerDay: 2
  triggers:
    wallet: fast
    minBountyUsd: 0.02
  unload: {}                     # {} enables a job with its defaults; an empty key would disable it
  adl: {}
  refresh:
    exclude: ["0x0000000000000000000000000000000000000001"]   # a market's address: never refresh it
    healthPokes: true            # pay for refreshes that open or end an ADL window
    healthPokeMaxCostUsd: 0.10
  terminalSettlement:
    finalize: true               # unpaid, but it releases everyone's payout
    finalizeMaxCostUsd: 0.5
  collect:
    thresholdUsd: 10
    maxAgeDays: 7
    forwardTo: "0x0000000000000000000000000000000000000002"   # a cold wallet
    forwardMinUsd: 100
  sweepExpired:                  # unpaid public service, within its daily budget
    lossBudgetUsdPerDay: 0.25
    minBatch: 10

# ---- How much ----
profit:
  minProfitUsd: 0.001
  gasSafetyMultiplier: 1.25
gas:
  maxFeeGwei: 1                  # never pay more than 1 gwei per gas
  backgroundMaxFeeGwei: 0.1      # collect, sweeps, finalize and forwarding wait for a quiet chain
  feeMultiplier: 2.0
  ethUsdFallback: 3000
  ethUsdFloor: 1000
  ethUsdMaxAgeSeconds: 60
budget:
  maxSpendUsdPerDay: 20
  maxSpendEthPerDay: 0.02        # the same cap in ETH, which no price feed can lift
  maxLossUsdPerDay: 5
  minEthBalance: 0.005
safety:
  pauseAfterReverts: 3
  pauseMinutes: 15

# ---- Around it ----
alerts:
  telegram:
    botToken: ${TG_BOT_TOKEN}
    chatId: "123456789"
  notify: [lowBalance, jobPaused, endpointDown, opportunity, dailySummary]
state:
  dir: /srv/keeper/state
log:
  level: info
  format: json                   # one JSON object per line, for a log collector
engine:
  tickSeconds: 0.5
  simCooldownSeconds: 2.0
  idleRefreshSeconds: 5.0
  snapshotSeconds: 60

Related Pages

• Wallets & Secrets: wallet types and the secrets rules.
• The Jobs: what each job’s keys change.
• Budgets & Losing Calls: profit, gas and budget together.
• Troubleshooting: every config error.