# Risk Score Methodology — Collar Guardrail

**Version:** 1.0
**Last updated:** 2026-10-06
**Applies to:** `evaluate_trade`, `evaluate_trade_paid`, and the REST
analyze endpoints (`/api/v1/analyze/trade`, `/api/v1/demo/analyze`,
`/api/x402/analyze`).

---

## 1. What the score is

The risk score is an integer from 0 to 100.

- **0** — no risk factors found.
- **100** — hard-blocked.

It is a **deterministic** function of the inputs below. The same request
produces the same score, given the same on-chain and registry state.
There is no machine-learning model in the loop.

| Score band | Decision | Meaning |
|------------|----------|---------|
| 0 – 30     | `allow`  | Policy passed. Safe to execute. |
| 31 – 70    | `warn`   | Soft violation. May proceed; reasons are advisory. |
| 71 – 100   | `deny`   | Hard violation. Do not execute. |

These bands are **indicative**. Individual categories can force a
decision outside its band — see §5, Hard Overrides.

---

## 2. Categories

The score is the sum of five independent categories. Maxima are listed;
**exact per-signal weights inside each category are internal** and may
change without notice.

### 2.1 Registry & identity (max 30)

- Is `contract_address` present in the official Robinhood Chain asset
  registry?
- Does it match the symbol in `asset`?
- Is the symbol a known alias or ticker collision?

A mismatch between `asset` and `contract_address` is treated as a
suspected fake-token attempt and is an **auto-deny** regardless of the
rest of the score.

### 2.2 Contract safety (max 30)

- Honeypot heuristics on the bytecode (owner-can-pause, blacklist,
  mint, tax, self-destruct).
- Sell-simulation result.
- Optional third-party signal (GoPlus) for unregistered tokens.

`check_token_safety` returning `severity=danger` forces an **auto-deny**
on the next `evaluate_trade` for the same contract, regardless of the
other categories.

### 2.3 Price & market data quality (max 15)

- Price source, descending quality: `oracle` > `uniswap_v4` >
  `fallback_default` > `unavailable`.
- Price staleness relative to the feed's expected cadence.
- Deviation between on-chain and fallback price.

`unavailable` price is a hard stop for non-trivial notional.

### 2.4 Wallet behavior (max 15)

- Realized daily loss vs the FOMO WARN and DENY thresholds.
- Cluster membership — shared funding source with known-bad wallets.
- Prior denials in the recent window.

### 2.5 Trade parameters (max 10)

- Notional vs the tier's max-trade ceiling.
- `max_slippage_bps` vs the asset's typical spread.
- Side (`buy` / `sell`) asymmetry.

---

## 3. How the score becomes a decision

1. Each category produces an integer in `[0, max]`.
2. The score is the sum, capped at 100.
3. The score maps to `allow` / `warn` / `deny` via the bands in §1.
4. Hard overrides (§5) are applied last.
5. If a hard override fires, the decision is `deny` and the score is set
   to the maximum of the override's category.

---

## 4. ADVISORY reasons

Any reason string prefixed with `ADVISORY:` is **non-blocking context**.
It appears on `allow` and `warn` decisions and does not change the
score. The absence of an `ADVISORY:` prefix means the reason inherited
its weight from the overall decision.

---

## 5. Hard overrides

These bypass the score bands and force `deny`:

- `asset` and `contract_address` mismatch (suspected fake token).
- `check_token_safety` returned `severity=danger` for this contract
  within the recent window.
- `price_source=unavailable` for a notional above the tier's advisory
  floor.
- Any response whose body contains an `error` key: **no verdict was
  produced.** Treat it as a hard stop.

---

## 6. What we do not disclose

- Exact per-signal weights within each category.
- The precise list of honeypot heuristic triggers.
- The cluster-detection algorithm.
- Thresholds for individual wallet-level rules.

These are withheld because publishing them enables adversarial tuning:
a bot that knows the exact weights can structure trades that score just
under a band. The categories above are stable; the weights are not.

---

## 7. Reproducibility

Every decision is written to the audit trail with:

- `audit_hash` — SHA-256 over the decision payload.
- `audit_seq` — monotonic sequence number.
- `request_id` — echoed idempotency key when supplied.

`verify_audit_trail(wallet)` recomputes each record's hash and validates
the chain. A healthy chain proves no record was edited, deleted, or
reordered after the fact.

---

## 8. Changelog

- **1.0** (2026-10-06) — initial published methodology.

---

Collar is independent third-party infrastructure. Not built, operated,
or endorsed by Robinhood. COLR is a separate token, not affiliated with
Robinhood Markets, Inc.