Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

FieldsMeaning
id, kind, versionLive contract identity, kind, and version
borrow_asset, collateral_assetComplete canonical NEP-141/NEP-245 identities
borrow_apr, usage_ratioCurrent snapshot APR and market utilization
borrowed, suppliedDecimal-adjusted borrowed and active supplied principal
borrowed_usd, supplied_usdFresh 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 when min(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_rate returns 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 now
    

    Note: Historical interest rate analysis requires an indexer for time-series data; the risk dashboard provides this.

Network Dependencies

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 under deployments/.
  • 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:

  1. Whoever spots an alert opens a war room, classifies severity, and takes the smallest reversible mitigation for their role.
  2. 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.
  3. User exits are preserved: no role can disable supply withdrawal requests or repayments.
  4. Recovery uses a patched market deployed through the registry and voluntary migration, never an in-place upgrade.
  5. 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.