Documentation
How Contrarian works
Everything you need to know about the decision firewall: the review lifecycle, the four adversarial lenses, what they score, and what this demo does — and deliberately does not — do.
01
Overview
Contrarian is a decision firewall. Instead of confirming what you want to do onchain, it actively argues against it: every transaction intent is run through four adversarial review lenses, scored for concern, and surfaced as a threat dashboard. You then choose to Execute Anyway or Cancel.
The premise: most onchain losses don't come from bad infrastructure, they come from unchallenged decisions. Wallets ask “confirm?” — Contrarian asks “are you sure, and here's why you might not be.”
Demo build
02
Quickstart
The fastest way in is the hosted dashboard — no wallet required to run a review:
To run it locally instead:
npm install npm run dev # http://localhost:3000
Then open the dashboard and describe an action in plain English, for example swap 100 USDC to SOL or stake 50 SOL with Marinade. Connecting a wallet (injected connector, Arbitrum) is optional and only affects the header — reviews work without it.
03
The review lifecycle
Every intent moves through a small state machine. If the input can't be parsed into a known action, the review ends in an error state and you can rephrase.
intent ──► analyzing ──► complete ──► executing ──► executed │ │ ▼ unparseable ▼ cancel error logged as CANCELLED
- Analyzing — the four lenses run in parallel; results arrive together after a short delay.
- Complete — scores, counter-arguments, and a verdict are on screen. The review waits for your decision.
- Executing → Executed — choosing Execute Anyway simulates the transaction and logs it to the activity feed with a mock hash.
- Cancelled — the review leaves the transcript and is logged as
CANCELLED. Cancelling is recorded on purpose: avoided mistakes are wins worth counting.
04
Lenses & scoring
Each lens answers one question and scores its level of concern from 0 to 100 — higher means more reason to pause.
Risk Analyst
What breaks?Looks for hard downside: thin or concentrated liquidity, unaudited or upgradeable contracts, exploit and depeg history, oracle deviation, liquidation thresholds, lock-up periods.
Market Skeptic
Why now?Looks for manufactured urgency: pump patterns, social-volume spikes, influencer promotion, unsustainable yields, and signs you are reacting to hype rather than acting on a plan.
Opportunity Cost
What instead?Compares the action against alternatives: better risk-adjusted yields, cheaper routes, splitting the entry into tranches, hedging, or simply waiting.
Behavioral Psychologist
Why you?Reads the decision against your own patterns: position sizes outside your rules, revenge trades, leverage spirals, yield-hopping, and pressure from other people.
Scores map to three severity bands:
| Score | Severity | Reading |
|---|---|---|
| 0–39 | Low | Acceptable |
| 40–69 | Med | Moderate — review advised |
| 70–100 | High | Critical — requires attention |
The verdict is derived from the average of the four scores: above 55 the review reads RECONSIDER; at or below it reads PROCEED WITH CAUTION. There is no third verdict and no hard block — the final decision is always yours.
05
Supported actions
The intent parser recognizes eight onchain action types from plain English. Anything it can't parse returns an error state with a prompt to rephrase.
| Action | Example prompt | Parsed fields |
|---|---|---|
| Swap | swap 100 USDC to SOL | amount, from, to |
| Stake | stake 50 SOL with Marinade | amount, token, protocol |
| Bridge | bridge 200 USDC to Arbitrum | amount, token, destination |
| Mint | mint an NFT from Mad Lads | collection |
| Lend | lend 500 USDC on Solend | amount, token, protocol |
| Borrow | borrow 100 USDC against SOL | amount, token, collateral |
| Transfer | send 10 SOL to 7xKv…abc | amount, token, recipient |
| Provide liquidity | provide liquidity 100 USDC + 100 SOL to Orca | pair amounts, protocol |
06
Wallet & execution
- Wallet connection uses wagmi + viem with the injected connector (MetaMask, Rabby, and similar).
- Supported chains are Arbitrum One and Arbitrum Sepolia; the header offers a one-click switch if you're elsewhere.
- Execution is simulated. Execute Anyway produces a mock transaction hash — no calldata is built and nothing is signed or broadcast.
- Review history lives in memory only and resets on reload.
07
Limitations
- Analysis is a deterministic local mock — phrase pools and weighted random scores, not a real risk assessment.
- No persistence: history, scores, and verdicts vanish on reload.
- The intent parser is regex-based and intentionally narrow; it covers the eight actions above and nothing else.
- Nothing in this product is financial advice.
On the roadmap: a real four-persona LLM call with structured output, transaction construction with pre-sign simulation, and persistent review history.
08
FAQ
Does Contrarian ever block a transaction?
No. Every review ends with Execute Anyway and Cancel. Contrarian is built to make you pause, never to take the decision away from you.
Is the analysis real?
Not in this demo — lens results come from a local mock. The interaction model, scoring bands, and data shapes are the real contract the production agent will fill.
Why does it log cancelled reviews?
Because a cancelled bad trade is the product working. The activity feed treats avoided mistakes as first-class outcomes, not discarded drafts.
Which networks are supported?
Wallet connection targets Arbitrum One and Arbitrum Sepolia. Since execution is simulated, reviews themselves are chain-agnostic.