Custos docs

Build with Custos

Add a market

The engine doesn't care what asset it prices. A market is a PriceGuard config plus its own pool and market contract, so adding ETH-USD is one entry in markets.json, a test run, a live feed check and a deploy. No Solidity changes.

What a market is#

Each entry in packages/foundry/markets.json is what PriceGuard needs for one asset:

KeyMeaning
chainlinkThe Chainlink aggregator for ASSET/USD on Hedera (the price)
supraSupra's push-oracle contract (the cross-check)
supraPairSupra's pair index for the asset
maxStalenessSeconds before a feed counts as Stale; at most 86,400 (1 day)
maxDeviationBpsLargest Chainlink/Supra gap allowed; at most 2,000 bps
refPrice8A typical price with 8 decimals, used by the tests

The shipped entry is HBAR-USD: Chainlink HBAR/USD, Supra pair 75, 43,200 s staleness, 500 bps. Leave it as it is; the app reads that market.

The recipe: ETH-USD#

  1. Add the entry to markets.json

    Next to "HBAR-USD" in packages/foundry/markets.json:

    packages/foundry/markets.json
    "ETH-USD": {
      "chainlink": "0xb9d461e0b962aF219866aDfA7DD19C52bB9871b9",
      "supra": "0x6Cd59830AAD978446e6cc7f6cc173aF7656Fb917",
      "supraPair": 19,
      "maxStaleness": 86400,
      "maxDeviationBps": 500,
      "refPrice8": 270000000000
    }

    Chainlink ETH/USD on Hedera testnet (8 decimals); the same Supra contract HBAR-USD uses, pair 19 (ETH/USDT). refPrice8 is $2,700.

  2. Check the config offline

    bash
    yarn workspace @sh/foundry check-markets ETH-USD

    Checks every entry against the limits PriceGuard enforces and fails if ETH-USD is missing. No network, no keys.

  3. Run the tests

    bash
    yarn foundry:test

    test/Markets.t.sol reads markets.json and runs every market through a full cycle at its refPrice8: the guard accepts the config, a long and a short open, the network liquidates the long on a 15% drop, the short closes at a profit, and the pool's books balance. A new entry is covered with no new test.

  4. Check the live feeds on testnet

    bash
    yarn custos:check-market:testnet --market ETH-USD

    Deploys only a PriceGuard with the ETH-USD config (a little HBAR), reads both feeds, prints the prices and status, and exits 1 if either feed doesn't answer. It signs with a keystore or DEPLOYER_PRIVATE_KEY from your shell. On 2026-10-03 it read Chainlink 2,657.85 and Supra 2,702.77 (PriceGuard 0x1eD9de81…51949D(opens in a new tab)).

  5. Deploy it

    bash
    yarn custos:deploy:testnet --market ETH-USD
    yarn custos:start:testnet --market ETH-USD

    Deploys a PriceGuard, pool and market for ETH-USD, then books its keeper's first tick. custos:demo:testnet takes the same flag. The addresses go to packages/foundry/deployments/296-eth-usd.json; deployedContracts.ts is left alone, so the app keeps showing HBAR-USD.

Choosing the staleness window#

maxStaleness must be longer than the slowest feed's gap between updates, or the market reads Stale: close-only, sweeps skipped, pool deposits paused. Push oracles update on deviation or on a heartbeat, and on testnet they push rarely.

  • Supra's testnet ETH/USDT was seen 8 hours old, so testnet ETH-USD needs the guard's maximum, 86,400 s.
  • On mainnet, where feeds update far more often, use about 3,600 s.
  • The 500 bps deviation check against Supra still catches a wrong price inside a long window. Supra quotes USDT, so leave room for a small gap from Chainlink's USD price.
  • Supra pairs 0 and 1 haven't updated on testnet in months; don't use them.

An agent did this on its first attempt#

The repo's .harness/ recipe asks a coding agent to add ETH-USD by following AGENTS.md, then grades the result from static checks up to a live feed check on testnet. A recorded run passed on attempt 1 of 3, changing 4 files and no contracts. See Hedera Harness.