A Pre-Transaction Fraud Warning System for the Stellar Network

Gryd Lock screens a Stellar transaction for fraud risk before the user signs it and warns them if the destination address or asset looks dangerous. It is a browser extension that hooks the wallet signing flow, reads the unsigned transaction, requests an on-chain risk score, and shows a clear four-tier warning. It never blocks a transaction — it warns, and the user decides.

Status: Design and early-build phase. The architecture and warning UX are defined; the detection intelligence is provided by a pluggable external risk oracle and is not yet wired to a live source. This README describes the system's design and roadmap, not a finished product.

On most chains, a fraud tool can intervene after a transaction is broadcast. On Stellar it cannot: transactions settle in roughly five seconds and cannot be reversed or halted once submitted. The only moment at which a user can still be protected is before they sign. Gryd Lock is built entirely around that constraint. It inserts a risk check into the narrow window between "user initiates a transaction" and "user approves it," and uses that window to surface a fraud signal the user would otherwise never see.

Ordinary Stellar users have no way to tell a legitimate destination from a fraudulent one at signing time. Wash-trading schemes, scam tokens, and social-engineering attacks all present as normal transactions in the wallet UI. Because settlement is final, a user who signs a malicious transaction has no recourse.

Pre-signing transaction scanners have proven effective on other ecosystems. Blowfish, Pocket Universe, and Fire all intercept the Ethereum signing flow, simulate or classify the pending transaction, and warn the user before approval. Gryd Lock adapts this pattern to Stellar. The concept transfers directly; the interception mechanism does not, because Stellar has no universal injected wallet provider. Each Stellar wallet exposes its own signing API, so interception is per-wallet. Gryd Lock therefore targets one wallet first — Freighter, the most widely used browser wallet in the ecosystem — and generalises to others once the pattern is proven.

1. Can an on-chain risk score be queried fast enough to warn a user before they sign a Stellar transaction, without adding friction that pushes users to disable the tool?
2. Which destination-level and asset-level signals indicate fraud reliably enough to justify a warning, without a false-positive rate that trains users to ignore it?
3. How should a pre-signing warning be designed so that a non-expert user understands the risk and acts on it, rather than clicking through it?

• Pre-signing interception: hooks the wallet signing flow and reads the unsigned transaction before the user approves it
• Four-tier warning system: maps a 0–100 risk score to Low / Elevated / High / Critical warnings
• Pluggable risk oracle: consumes a risk score from a Soroban smart contract behind a stable adapter interface (grydlock-oracle-adapter); holds no scoring logic of its own
• Non-blocking by design: never blocks a transaction — it warns, and the user always decides
• Freighter-first targeting: Stellar has no universal injected wallet provider, so interception is implemented per-wallet, starting with Freighter and generalising once proven

graph TD
    A[User initiates transaction in a Stellar wallet] --> B[Gryd Lock intercepts the unsigned transaction via the Freighter signing flow]
    B --> C[Decode transaction XDR: extract destination address / asset]
    C --> D[Query the on-chain risk oracle via Soroban: risk score 0-100]
    D --> E[Map score to a warning tier: show warning]
    E --> F[User proceeds or cancels: Gryd Lock never blocks]

Gryd Lock consumes a 0–100 risk score for a destination address or asset from an on-chain risk oracle — a Soroban smart contract exposing a get_score() read. The oracle is a pluggable component behind a stable interface (grydlock-oracle-adapter); Gryd Lock is agnostic to which engine produces the score and holds no scoring logic of its own. This separation keeps the warning layer independent of any particular detection backend.

The build follows five phases, ordered so that nothing is written before its foundation exists.

1. Literature review — pre-signing interception, blockchain transaction finality, and existing scanner UX. Establishes what has worked elsewhere and what must change for Stellar.
2. System design — the full architecture above is fixed before code, including the wallet-specific interception strategy and the adapter interface.
3. Build — the browser extension, the Freighter signing proxy, the oracle adapter, and the warning UI.
4. Testing — labelled destinations on Stellar testnet (grydlock-testkit). Measure query latency, classification accuracy, and false-positive rate.
5. Evaluation — user comprehension of the warning and its real protective value.

• Latency: time from signing intent to displayed warning. Target: fast enough to feel instant, so users do not disable the extension to avoid the wait.
• Accuracy: correct tier assignment against a labelled set of known scam and wash-trading destinations on testnet.
• False-positive rate: proportion of clean destinations wrongly warned. This is the metric that determines whether users keep the tool on.
• Comprehension: whether non-expert users correctly interpret and act on each tier. A warning nobody understands provides no protection.

Gryd Lock is in the design and early-build phase.

• ✅ Architecture, warning tiers, and interception strategy defined
• ✅ Warning UI exists as an early stub driven by hardcoded scores
• ⬜ Real transaction interception — not yet built
• ⬜ Live oracle connection — not yet built
• ⬜ No functional fraud detection is claimed at this stage

This is deliberately honest: a pre-signing warning layer is only as good as the intelligence behind it, and that intelligence is not yet live.

• Lock the build form (browser extension) and the first target wallet (Freighter)
• Build the smallest working version: an extension popup that renders one score across the four tiers (early stub)
• Wire the oracle adapter against a stub score on testnet; confirm the query path end to end before touching real interception
• Implement Freighter signing interception: proxy signTransaction, decode the XDR, extract the destination, and route it through the adapter
• Connect the adapter to a live on-chain risk oracle and replace stub scores with real ones
• Run the testnet evaluation and tune warning tiers against the false-positive target
• Generalise interception beyond Freighter once the pattern holds

Recommendation: do not implement real interception until the oracle adapter returns a real score from testnet. Interception without a working risk source is a warning system with nothing to warn about.

• TypeScript / JavaScript — extension logic
• React — warning UI inside the extension popup
• Stellar SDK (JS) — decoding unsigned transaction details before signing
• Soroban SDK — querying the on-chain risk oracle
• Stellar Testnet — all development and evaluation

Transaction finality and interception

• Stellar Developer Documentation — stellar.org/developers
• Soroban smart contract documentation
• Blowfish and Pocket Universe technical blogs (Ethereum pre-signing scanners — closest analogues)

Fraud detection theory

• Bart Baesens — Fraud Analytics Using Descriptive, Predictive, and Social Network Techniques
• Benford, F. (1938) — the original first-digit law paper

Warning UX

• Steve Krug — Don't Make Me Think (a warning nobody understands is useless)

Gryd Lock is a standalone Stellar ecosystem project. Risk intelligence lives on-chain behind a pluggable oracle interface; warning logic lives in the user's browser; no transaction is ever blocked without the user's explicit consent.