Monitoring and Risk Management
Templar Protocol runs real-time monitoring on its NEAR markets and proxy oracles and on its Stellar curated vaults, and publishes its risk data openly. This page describes the monitoring and alerting stack, the public risk dashboard, the operational bots, how to run protocol health checks yourself, and how risk is managed and contained.
Real-Time Monitoring and Alerting
Templar runs two complementary monitoring systems with 24/7 human coverage:
- Hypernative monitors the Stellar curated vaults for exploit detection, invariant violations, anomalous privileged calls, and counterparty risk signals.
- Custom alerts built by Templar monitor the NEAR markets and proxy oracles. Alert definitions are version-controlled in the templar-monitoring repository and changed only through reviewed pull requests.
Alerts from both systems are published to the public Templar alerts Telegram channel, so integrators and liquidity providers see the same signals the team does.
What Is Monitored
The alerting covers:
- Oracle failure or price deviation beyond threshold
- Position approaching liquidation
- Liquidation executed
- Large position events (whale alerts)
- Bad debt creation
- Utilization rate crossing critical thresholds
- Smart contract pause or emergency admin action
Coverage and Escalation
Templar's security policy defines an on-call rotation among the multisig signers, who are distributed across multiple time zones, so that a responder is within working hours at all times. Every alert is classified by severity; critical alerts page all signers and open a war room following the emergency runbooks. See Incident Response below.
Compliance Screening
Separately from the protocol alerts above, Templar screens on-chain activity against sanctions and risk signals from Predicate and TRM Labs. SEVERE-labelled accounts interacting with Templar contracts trigger a Telegram notification. Details are in the templar-monitoring repository.
Live Risk Dashboard
data.templarfi.org is Templar's public, real-time risk dashboard. It is built directly from on-chain data (contract state over NEAR RPC, blocks and events from NEARData and FastNear) with USD prices from Pyth, Pyth Lazer, and RedStone, and it is the same tool the team uses for risk modeling. Every view can be filtered per market and viewed in aggregate.
Ops Console
- Collateral Coverage: total collateral against outstanding borrows, a 90-day coverage trend, coverage by collateral asset, and a per-asset breakdown with each market classified as healthy, below target, or undercollateralized. Markets whose price feed was stale or missing at scan time are flagged rather than silently counted.
- Liquidation Proximity (live): positions at risk (health factor at or below 1.2), aggregate coverage ratio, average health factor, the health-factor distribution ("collateral wall"), and scenario sliders showing how a price drawdown moves positions toward liquidation.
- Oracle Health: assets scanned, stale feeds, and missing feeds; per-feed staleness, spread, and confidence; effective (protocol-side) versus raw price; and a per-asset oracle state table.
- TVL & Revenue: total supply, total borrowed, and protocol TVL across day, week, month, and quarter; protocol fees and cumulative revenue.
Risk Committee
- Utilization & Rates: current utilization against each market's kink, the interest rate curves, and 90-day history.
- Concentration Risk: top-1 and top-5 borrower share, Herfindahl-Hirschman indices for borrowers, collateral providers, and suppliers, single-borrower and single-provider exposure, and the distributions and top lists behind them.
Strategic
- Supply-Side Analytics: deposit and withdrawal flows, net supply flow, depositor count, average deposit age, accrued yield, and advertised supply APY; borrow and repay flows and net loan flow, with a market selector.
- Positions at Risk: position counts by risk tier (liquidatable below 1.0 health factor, critical below 1.10, warning below 1.25, healthy) with an hourly trend.
- Ledger Events: deposits, withdrawals, borrows, repays, and liquidations, newest first, filterable by market.
- Intents Transfers: where value went after withdrawal, showing bridge-outs and NEAR transfers by account through the NEAR Intents settlement layer, which block explorers cannot show.
The same data drives the position and utilization alerts above. Total value locked is also tracked independently on DefiLlama.
Operational Services
The protocol runs the following off-chain services, all open source under service/:
- Liquidator: monitors borrow positions across all registered markets, refreshes oracle prices, and executes liquidations of under-collateralized positions. Liquidation is permissionless and is performed primarily by third-party liquidation bots; Templar's bot is one participant among them, not a privileged one.
- Accumulator: applies interest to borrow positions on a schedule so that accrued liability is always reflected on-chain.
- Market monitor: scans every market and sends Telegram alerts for positions at risk of liquidation, classified into health zones by distance from the maintenance ratio.
- Oracle updaters: the RedStone bridge service, together with the oracle-update paths built into the liquidator and relayer, fetch signed Pyth Lazer and RedStone payloads, submit them to the on-chain adapters, and refresh proxy oracle prices ahead of price-dependent actions.
- Relayer: relays signed delegate actions so that accounts without NEAR can interact with the protocol, and refreshes oracle prices before the actions it relays.
Bots can be halted at any time as a containment step. They have no privileged access to markets: everything they do, anyone can do.
Gas Usage Monitoring
Gas analysis tools provide performance insights:
./script/gas-report.sh
This generates detailed reports on function execution costs, snapshot iteration limits, and performance bottlenecks.
Protocol Health Checks
Anyone can reproduce the core health checks with view calls. Examples use near-cli-rs.
Live Fleet Queries
tmplrmgr query scans markets, proxy oracles, or proxy-oracle governance contracts
through typed gateway reads. It never signs transactions or updates oracle storage.
Use --network mainnet explicitly; the CLI defaults to testnet.
tmplrmgr query fields markets
tmplrmgr query fields proxy-oracles
tmplrmgr query fields proxy-governance
tmplrmgr query assets
tmplrmgr --network mainnet query markets --registry-id v1.tmplr.near \
--filter 'collateral_asset = BTC' \
--filter 'borrow_asset = USDC' \
--filter 'borrow_apr >= 10%' \
--include oracle.governance \
--sort borrowed --descending
Registry records discover candidate account IDs only; current contract kinds
are read with bounded concurrency. Confirmed deleted accounts are skipped without
making the scan incomplete; failed classifications and live, unrecognized
contracts remain visible.
The version field always comes from the running contract's NEP-330 metadata,
never the registry's original version key. Alternatively, repeat
--account-id <account> to query specific accounts instead of a registry.
Filters have exactly three whitespace-separated terms: field operator value.
Repeat --filter for AND; there is no boolean-expression language. Numeric and
version fields support =, !=, <, <=, >, and >=; identity and kind fields
support equality and inequality only. Versions compare numeric
major.minor.patch components. APR and utilization accept 10% or 0.1;
USD and token amounts use plain nonnegative decimals, without currency symbols
or scientific notation.
Numeric predicates, sorting, and output use the same fixed-point quantization as
parsed decimal text, so emitted values can be reused as thresholds and derived
amounts respect equality and inclusive bounds without approximate comparisons.
| Fields | Meaning |
|---|---|
id, kind, version | Live contract identity, kind, and version |
borrow_asset, collateral_asset | Complete canonical NEP-141/NEP-245 identities |
borrow_apr, usage_ratio | Current snapshot APR and market utilization |
borrowed, supplied | Decimal-adjusted borrowed and active supplied principal |
borrowed_usd, supplied_usd | Fresh indicative USD values of those principal amounts |
Fields and kind values use snake_case, matching gateway JSON (proxy_oracle,
proxy_governance). CLI subcommands and flags retain their usual hyphenated names.
Defaults return all non-USD root fields, including market metrics. Metrics share
one cached snapshot read per returned market. Use --select id,version for a
minimal projection; filtering and sorting can still require other reads.
--include oracle.governance adds the default fields at each relationship along
that path. Repeat --include or separate paths with commas. --usd adds the two
USD fields to market output; it does not implicitly expand relationships.
Explicit USD filters, sorting, or selection also enable the required valuation.
Non-USD filters run before USD filters. Output-only reads run after --limit.
--concurrency bounds ordinary contract reads (default 8, maximum 32).
USD dependency discovery, adapter verification, and price resolution use separate
batches with fixed concurrency 8.
--limit applies after filtering, sorting, and mapping, not to registry discovery.
Asset aliases are explicit sets of exact identities, discoverable through
query assets; aliases are case-insensitive, while exact identities remain
case-sensitive. BTC, WBTC, hemiBTC, and SolvBTC are distinct. USDC includes
several explicitly catalogued wrappers. Unknown assets remain queryable by their
full nep141:<contract> or nep245:<contract>:<token-id> identity. Token-reported
symbols and shared oracle feeds do not silently establish asset equivalence.
Relationships compose through dotted paths:
- Market
oracle: the configured oracle, including legacy direct oracles. - Proxy
governance: its owner, only when identified as governance and pointing back to that proxy. Plain/self-owned accounts do not imply governance. - Governance
oracle: its governed proxy.
# Return markets whose configured proxy is at or below this current version.
tmplrmgr --network mainnet query markets --registry-id v1.tmplr.near \
--filter 'oracle.kind = proxy_oracle' \
--filter 'oracle.version <= 0.4.1' \
--include oracle.governance
# Return distinct governing contracts for BTC-collateral markets.
tmplrmgr --network mainnet query markets --registry-id v1.tmplr.near \
--filter 'collateral_asset = BTC' \
--map oracle.governance --include oracle
Filters and sorting refer to the root type and run before mapping. Selection,
inclusion, and --usd refer to the mapped type when mapping is present.
Each returned object includes its id, including selected relationships.
Missing relations do not produce mapped rows. Related reads are cached by
account and operation; paths are limited to 16 relationship edges.
Dotted query paths describe nested JSON, not literal dotted keys. For example,
oracle.version appears inside the oracle object, accessible through
jq '.rows[].oracle.version'. Unrequested relationships are omitted; requested
absent relationships are null. An unavailable field on a known related account
is null within its object rather than making that whole relationship absent.
Expansion follows only requested paths, never every edge of a relationship cycle.
USD valuation fetches fresh signed Lazer/RedStone payloads, verifies them through
the deployed adapters, then resolves the proxy's configured price and
transformations from supplied inputs. Requests are deduplicated across the scan.
Every required source, including its transformation, must yield a positive,
representable price and satisfy the market's maximum age. The query uses
oracle.resolvePriceAllSources so a failed transformation cannot be hidden by a
healthy fallback source. There is no partial-source valuation, stored-price
fallback, or stablecoin peg assumption.
Lazer requires PYTH_LAZER_API_KEY or --pyth-lazer-api-key only when
used. RedStone requires REDSTONE_API_KEY or --redstone-api-key and its
Node.js bridge/runtime only when used; provider options appear in
query markets --help. Classic Pyth-backed dependencies currently have no
verified provider preview and therefore produce unavailable USD values.
Token decimals must be 0–38; price exponents must be -38–115.
Borrowed principal includes in-flight borrowing, but not accrued borrower interest or fees. Active supplied principal includes currently activatable incoming deposits, not total supplier claims. Utilization is borrowed/active principal, zero if either is zero, and capped at one. Neither USD field is TVL. Fresh indicative valuations do not assert that the proxy's cached price or circuit breakers would permit a transaction.
Results are JSON: scanned counts registry candidates of all kinds (or explicitly
requested accounts), including deleted accounts skipped during classification.
matched counts roots of the requested kind surviving all filters, and rows
contains the selected output.
Selected field values, including numbers, are strings. Missing values are null,
never zero; they match no predicate, including !=, and sort last in either
direction. Account ID breaks sort ties deterministically.
This is a best-effort live scan, not a block-pinned snapshot. Failed reads remain
visible in failures and set complete: false; a partial scan exits successfully,
so automation must inspect complete. Invalid arguments and failed registry
discovery exit nonzero. Unknown/non-numeric live versions are unavailable rather
than replaced by registry versions.
Market Status
# Get market configuration (immutable after deployment)
near contract call-function as-read-only <market-address> get_configuration json-args {} network-config mainnet now
# Check current market snapshot
near contract call-function as-read-only <market-address> get_current_snapshot json-args {} network-config mainnet now
# Get borrow asset metrics (supplied, borrowed, available)
near contract call-function as-read-only <market-address> get_borrow_asset_metrics json-args {} network-config mainnet now
# List all deployed markets from the registry
near contract call-function as-read-only v1.tmplr.near list_deployments json-args '{"offset": 0, "count": 100}' network-config mainnet now
paid_to_fees is the decimal-string amount of repaid interest and fees
currently available to pay supplier yield. It is a market-wide,
first-come-first-served pool: it is not accrued yield, per-user reserved
cash, or a guarantee that a withdrawal will execute. A raw JSON response
that omits this field is from a legacy deployment and differs from an
upgraded market explicitly reporting "0"; Rust consumers deserialize an
omitted field as zero for compatibility and therefore lose that distinction.
The field appears on live markets only after a released version containing it
has been deployed or upgraded.
Oracle Health
Markets read prices from the oracle account in their configuration. Newer markets read a proxy oracle; some older markets still read pyth-oracle.near or lst.oracle.tmplr.near directly (for example ibtc-iethusdc.v1.tmplr.near and stnear-usdc-1.v1.tmplr.near), so check the market's get_configuration output first. For a proxy-backed market, check the proxy first, then the underlying adapters. The example below uses ixlmdejaaa-ixlmusdc-2.v1.tmplr.near, whose configuration points to proxy-oracle-ixlmdejaaa-ixlmusdc-2.v1.tmplr.near; take the price identifiers from that configuration.
# Latest cached price for a feed and its status (accepted, blocked, stale, failed)
near contract call-function as-read-only proxy-oracle-ixlmdejaaa-ixlmusdc-2.v1.tmplr.near get_cached_proxy_price json-args '{"id": "<price-id>"}' network-config mainnet now
# Circuit breaker state and accepted price history for a feed
near contract call-function as-read-only proxy-oracle-ixlmdejaaa-ixlmusdc-2.v1.tmplr.near get_proxy_circuit_breaker_set json-args '{"id": "<price-id>"}' network-config mainnet now
# What the market will actually see: accepted prices no older than <age> seconds
near contract call-function as-read-only proxy-oracle-ixlmdejaaa-ixlmusdc-2.v1.tmplr.near list_ema_prices_no_older_than json-args '{"price_ids": ["<price-id>"], "age": 60}' network-config mainnet now
# Underlying sources
near contract call-function as-read-only pyth-oracle.near get_price json-args '{"price_identifier": "<pyth-price-id>"}' network-config mainnet now
near contract call-function as-read-only redstone-adapter.v1.tmplr.near read_price_data_for_feed json-args '{"feed_id": "<feed-id>"}' network-config mainnet now
# Legacy LST oracle adapter
near contract call-function as-read-only lst.oracle.tmplr.near get_price_data json-args '{}' network-config mainnet now
Provider status pages: Pyth Network Price Feeds and Pyth Network Status; RedStone.
Market Data Analysis
-
Supply Positions: Monitor individual and aggregate supply positions
near contract call-function as-read-only <market-address> list_supply_positions json-args '{"offset": 0, "count": 100}' network-config mainnet now -
Withdrawal Queue: Check pending withdrawal requests
near contract call-function as-read-only <market-address> get_supply_withdrawal_queue_status json-args {} network-config mainnet now -
Historical Snapshots: Analyze market history
near contract call-function as-read-only <market-address> list_finalized_snapshots json-args '{"offset": 0, "count": 10}' network-config mainnet now -
Utilization Rate: Calculate from borrow asset metrics as
borrowed / (borrowed + available)near contract call-function as-read-only <market-address> get_borrow_asset_metrics json-args {} network-config mainnet now -
Supplier Yield Availability:
min(accrued_yield, paid_to_fees)is the largest yield-only request that can be paid without consuming principal. Such a request meets the configured minimum only whenmin(accrued_yield, paid_to_fees) >= supply_withdrawal_range.minimum. This is not a general withdrawal-eligibility check: principal may cover the remainder of a larger request. Existing eligibility checks still apply, and other withdrawals can consume the shared pool before execution. -
Last Yield Rate:
get_last_yield_ratereturns the most recently computed supply yield rate. It is an expected average over time, not a spot rate; supply positions earn yield the instant it is distributed.near contract call-function as-read-only <market-address> get_last_yield_rate json-args {} network-config mainnet nowNote: Historical interest rate analysis requires an indexer for time-series data; the risk dashboard provides this.
Network Dependencies
- NEAR Network: NEAR Status
- NEAR Intents (cross-chain deposits and withdrawals): NEAR Intents Status
- Chain Signatures (MPC signing network): live operator set and threshold; see Chain Signatures MPC Network
- Pyth Network: Pyth Network Status
Templar's cross-chain collateral and stablecoin flows depend on NEAR infrastructure: NEAR Intents, the Omnibridge, Chain Signatures (the MPC network), and nearcore itself. The security audits of those dependencies (nearcore assessments by Trail of Bits and Sigma Prime; NEAR Intents reviews by Hacken, Guvenkaya, zkSecurity, and Aurora Labs; Omnibridge audit reports; and the NEAR One reports on the MPC Chain Signatures network) are collected in the NEAR dependency audits folder. Contingency procedures for a dependency incident are in the emergency runbooks.
Risk Management
Economic Risk Assessment
- Market parameters: every market's collateralization ratios, interest rate curve, usage ratio, and liquidation spread are immutable and readable via
get_configuration. The specifications they were deployed from are version-controlled underdeployments/. - Real-time risk modeling: coverage, liquidation proximity, positions by risk tier, concentration, and utilization analysis for every market is continuous on the risk dashboard, rather than a periodic simulation.
- Oracle reliability: divergence and downtime are tracked per source and per proxy feed, and the dashboard's Oracle Health view shows staleness, spread, and confidence per feed; see Oracle Health.
- Liquidation efficiency: executed liquidations and positions at risk are alerted in real time and visible in the dashboard's Liquidation Proximity, Positions at Risk, and Ledger Events views.
- Individual positions: My Account in the Templar app.
Risk Mitigation Strategies
- Isolated markets: one collateral and one borrow asset per market, so no cross-asset contagion.
- Immutable markets: no parameter can be changed after deployment, by anyone.
- Conservative parameters: maintenance ratios above liquidation ratios, bounded liquidation spreads, and usage-ratio caps that preserve withdrawal liquidity.
- Multi-source oracles with circuit breakers: see Oracles.
- Defensive valuation: collateral valued at the lower confidence bound and liabilities at the upper bound.
- Liquidation incentives: permissionless, partially-liquidating liquidations with a configured spread so that positions are restored to health promptly.
- Dynamic interest rates: utilization-driven curves that price liquidity scarcity and pull utilization back toward the optimum.
- Curated vaults: professional curators manage vault allocations under caps, timelocks, and an independent Sentinel; see the Curator Guide.
Incident Response
Templar's response to an alert follows the public emergency runbooks:
- Whoever spots an alert opens a war room, classifies severity, and takes the smallest reversible mitigation for their role.
- Containment ladder: halt Templar's own bots; trip the affected proxy oracle feed (freezing borrows, collateral withdrawals against debt, and liquidations on markets that read a proxy oracle); on vaults, Sentinel pause or restriction tightening, allocator abort or rebalance, then curator cap-to-zero or market removal.
- User exits are preserved: no role can disable supply withdrawal requests or repayments.
- Recovery uses a patched market deployed through the registry and voluntary migration, never an in-place upgrade.
- Stand-down requires sign-off from at least two roles, and user-affecting incidents produce a post-mortem.
For the protocol's overall security posture, see Security.