An on-chain compliance firewall for stablecoins and tokenized stocks. The token itself refuses to move funds to hackers, wallet drainers and sanctioned addresses. It runs live on Arbitrum Sepolia and Robinhood Chain testnet, sharing one threat registry kept in sync across both chains.
Live demo: https://chain-guard-frontend.vercel.app · Video: · Contracts: verified on Blockscout
A broker is legally required to screen who it trades with. An ERC-20 screens no one. As stock tokens on Robinhood Chain and stablecoins like USDG start bridging regulated finance and DeFi, an address behind a $292M bridge exploit, a phishing kit or an OFAC listing can still receive and trade them. Today's only answer is off-chain: an exchange freezes a deposit after the fact. Nothing stops the transfer itself.
| 🛡 Blocks at the token level | Every transfer, mint and burn asks a shared registry about both parties. Severity 3 makes it revert with AddressBlocked(account, category, severity). Severity 1–2 lets it through and emits an on-chain ComplianceWarning, the "yellow flag" banks use. |
| 🗂 Real threat data | 10,232 labelled addresses from public sources: OFAC, exploit attributions (Kelp DAO, Bybit, Ronin, Multichain, Nomad…), ScamSniffer, Etherscan, MyEtherWallet, and on-chain-verified Tornado Cash pools. Every check also queries GoPlus live (SlowMist, BlockSec). |
| ⚖️ Spam-resistant reporting | Anyone can report an address by staking ETH. A 2-of-3 committee confirms it (stake back + 20%) or rejects it (stake slashed, half goes to the wrongly accused). Until quorum, a report is only a soft warning, so nobody can freeze funds by griefing. |
| 🔗 One registry, two chains | A relayer mirrors every flag between Arbitrum Sepolia and Robinhood Chain. Measured on testnet: 3.95 s from committee quorum on Arbitrum to the address being blocked on Robinhood Chain. |
![]() |
![]() |
| Kelp DAO exploiter: blocked on both chains, with sources and on-chain history | Sending USDG to it reverts inside the token contract |
On the live site (no wallet needed for steps 1–2):
- Click Kelp DAO exploiter → BLOCKED, category EXPLOIT, with threat-feed matches and its on-chain history on both chains.
- Click Tornado Cash 1 ETH → WARNING (mixer, allowed but monitored). Click vitalik.eth → CLEAN.
- Connect MetaMask on Robinhood Chain testnet. In Firewall test: Faucet (free demo USDG), then send to the Kelp exploiter → reverts. Send to vitalik.eth → goes through.
- Click Bybit exploiter → KNOWN THREAT: public feeds know it, but the registry doesn't enforce it yet. Click Report to registry, stake and submit. It becomes a soft warning until the committee confirms it.
Networks for MetaMask:
| Network | Chain ID | RPC | Faucet |
|---|---|---|---|
| Arbitrum Sepolia | 421614 | https://sepolia-rollup.arbitrum.io/rpc |
Alchemy |
| Robinhood Chain testnet | 46630 | https://rpc.testnet.chain.robinhood.com/rpc |
Robinhood |
flowchart LR
subgraph ARB["Arbitrum Sepolia"]
RA[ComplianceRegistry] --> GA[ComplianceGuard]
GA --> TA["USDG / TSLA tokens"]
end
subgraph RH["Robinhood Chain testnet"]
RR[ComplianceRegistry] --> GR[ComplianceGuard]
GR --> TR["USDG / TSLA tokens"]
end
REP["Reporter (stakes ETH)"] -->|flagAddress| RA
COM["Committee 2-of-3"] -->|confirm / reject / lift| RA
FEEDS["Public feeds: OFAC, exploits, ScamSniffer, Etherscan"] -->|flagBatch + confirmBatch| RA
RA <-->|"mirrorBatch (relayer)"| RR
UI["Web app"] -.reads.-> RA & RR
UI -.live lookup.-> GP[GoPlus API]
| Contract | Responsibility |
|---|---|
ComplianceRegistry |
The list of risky addresses. Each Flag has a category (SANCTIONED, EXPLOIT, PHISHING, MIXER, RUGPULL, SCAM_REPORTED), a severity 1–3, an evidence hash and URI, the reporter, a status and the source chain. It handles staking, committee votes, appeals, expiry, payouts (pull-based withdraw), batch import (flagBatch / confirmBatch) and cross-chain mirroring (mirrorBatch). riskOf(address) is the one call integrations need. |
ComplianceGuard |
The enforcement hook shared by any number of tokens. check(from, to, amount) reverts or warns. preview(from, to) lets UIs predict the outcome before sending. |
ComplianceGuardedERC20 |
An abstract ERC-20 that calls the guard from _update (OpenZeppelin v5), so transfers, mints and burns are all screened. Any token can inherit it. |
MockUSDG, MockStockToken |
Demo stablecoin (6 decimals) and tokenized TSLA, with faucets. The real USDG isn't available on these testnets. |
- Stake to report. Reporters outside the committee lock at least
minStake. - Pending = soft only.
riskOfcaps an unconfirmed flag at severity 1, so a griefer can buy a yellow flag but can never freeze funds. - Quorum decides. 2 of 3 committee members must confirm or reject. A member's own report counts as their vote.
- Incentives. Confirmed: stake back + 20% from the reward pool. Rejected: the stake is slashed, 50% to the wrongly accused address and 50% to the pool. Farming compensation with a self-report loses half the stake.
- Due process. The flagged address can
fileAppeal, and the committee canunflagAddress. If the committee never acts, anyone canexpireFlagafter 3 days and the reporter is refunded.
- Each flag records its
sourceChainId. Only that chain can vote on or resolve it, and mirrored copies reject local votes (ForeignFlag). - Mirrors are full snapshots that only move forward: a newer round, or the same round with a later status. Replays and out-of-order deliveries are skipped (
StaleMirror). - A mirror never overwrites a live flag governed by another chain (
MirrorConflict), so stakes stay safe. - The relayer queues the latest snapshot per address and writes in batches of 100. After a restart it rescans both registries and catches up.
- Always on, no server. A GitHub Actions job runs the relayer in one-shot mode every ~5 minutes. Running it live (
scripts/testnet-relayer.sh start) gives the ~4 s sync. Both modes can run together.
build-intel.ts compiles public feeds into one labelled database (threat-db.json). import-intel.ts writes it on-chain through committee batch votes (~176k gas per address).
| Source | Addresses | Category · severity |
|---|---|---|
| US Treasury OFAC SDN list | 120 | SANCTIONED · 3 |
| Exploit attributions: curated + Etherscan labels (Ronin, Multichain, Nomad, BadgerDAO, KyberSwap…) | 300 | EXPLOIT · 3 |
| Malicious contracts & deployers (Forta labelled datasets) | 611 | PHISHING / EXPLOIT · 3 |
| Etherscan phish/hack labels (Forta labelled datasets) | 7,077 | PHISHING · 3, SCAM · 2 |
| ScamSniffer drainer blacklist | 2,530 | PHISHING · 3 |
| MyEtherWallet darklist | 652 | PHISHING / SCAM |
Tornado Cash pools, verified on-chain via denomination() |
9 | MIXER · 2 (warn, don't block) |
On testnet, the 1,033 highest-value entries (OFAC, exploits, mixers, malicious contracts) are enforced on-chain on both chains. The app screens every address against the full database plus GoPlus. A known threat that isn't enforced yet shows as KNOWN THREAT, with a one-click report. The UI keeps two things separate: the threat source (e.g. "Public feed: OFAC") and the account that submitted it on-chain (e.g. "Committee member #1 · feed import").
All source code is verified on Blockscout.
| Contract | Arbitrum Sepolia (421614) | Robinhood Chain testnet (46630) |
|---|---|---|
| ComplianceRegistry | 0x4FC00B31…9177b |
0xe65245bC…50F74 |
| ComplianceGuard | 0x02aA4623…35F61 |
0x4aAE0065…Bba73 |
| USDG (demo) | 0xc986f96a…d0eCb |
0x6B65976C…4B4BB |
| TSLA Stock Token (demo) | 0x6F7948cf…5d035 |
0x97125C80…A90Dc |
Committee (2-of-3): 0xD843CBe0…944DA, 0xC264A0D0…ba1d5, 0x7e125358…56AF3. Relayer: 0x31436123…667C5.
# tests
cd contracts && forge test # 26 tests, incl. fuzzing of stake accounting
# full local stack: two anvil chains with the real chain IDs, deploy, relayer, ~1k threats imported
(cd relayer && bun install) && (cd frontend && bun install)
scripts/local-up.sh # FULL_IMPORT=1 imports all 10k (needs ~1.5 GB RAM per chain)
cd frontend && bun run dev # http://localhost:5173, with built-in demo wallets (no MetaMask)
scripts/local-down.sh
# app against the live testnet deployment
cd frontend && bun run dev:testnetDeploy your own copy to the testnets
cp .env.example .env # deployer key, 3 committee addresses, relayer address
scripts/deploy-testnet.sh # both chains, writes contracts/deployments/testnet/*.json
scripts/verify.sh # Blockscout (Sourcify fallback)
scripts/testnet-relayer.sh start # live relayer, status on :8788
cd relayer && MODE=testnet CHAIN=arbitrum COMMITTEE_KEYS=0xk1,0xk2 \
SOURCES=ofac,exploits,mixers,contracts bun src/import-intel.ts
cd relayer && bun src/build-intel.ts # refresh the threat feedsThe site deploys to Vercel from the repo root (vercel.json). For the scheduled relayer, add the repository secret RELAYER_PRIVATE_KEY.
contracts/ Solidity (Foundry): registry, guard, guarded ERC-20, demo tokens, tests, deploy script
relayer/ Bun + viem: cross-chain relayer (live / --once), threat-feed builder, on-chain importer
frontend/ Vite + React + wagmi/viem web app (reads both chains directly, no backend)
shared/ chain metadata, generated ABIs, threat-intel logic and compiled database
scripts/ local stack, deploy, verify, relayer helpers
docs/ screenshots
- Relayer. It is a single trusted key today. Next step: carry flags over Arbitrum native messaging, Hyperlane or CCIP, so a mirror comes with a proof instead of a signature.
- Committee. Fixed at deploy time. Next step: rotation and threshold changes through governance, and per-category committees (e.g. sanctions vs. scams).
- Tokens. USDG and TSLA here are demo tokens with the standard ERC-20 interface. Real issuers would plug
ComplianceGuardinto their own transfer-restriction hooks. - Evidence. It is a hash plus a URI emitted in events. Pinning evidence to IPFS/Arweave is future work.




