🔄 REVERSO Protocol

Reversible Transaction Protocol for EVM Chains

Time-locked transfers with cancel, recovery, and insurance — deployed on 7 chains.

🌐 Live Demo • 📄 Documentation • 🔌 API • 🛡️ Security

📊 Project Status

Component	Status	Details
🔐 ReversoVault	✅ Deployed on Ethereum	Verified on Etherscan — 1,194 lines, 5-layer protection
🛡️ EmergencyGuardian	✅ Deployed on Ethereum	Verified on Etherscan — Multi-sig + 24h timelock
👁️ ReversoMonitor	✅ Deployed on Ethereum	Verified on Etherscan — Anomaly detection + auto-pause
🧪 Test Suite	✅ 163 tests passing	131 Hardhat (contracts) + 32 Jest (API) — HMAC, validation, denylist, plans
🔌 Enterprise API	✅ Live	HMAC auth, email verification, password reset, fraud denylist, webhooks with retry
🌐 Website	✅ Live — reverso.one	Interactive demo with wallet connection
⛓️ Multi-chain	✅ 7 Chains Live	Ethereum, BSC, Base, Arbitrum, Polygon, Optimism, Avalanche
🔀 Fuzz Testing	✅ 13,000+ runs	13 property tests × 1,000 random inputs (Foundry)

All 3 contracts deployed and wired on 7 chains: Ethereum, BSC, Base, Arbitrum, Polygon, Optimism, Avalanche.

🎯 The Problem

Blockchain transactions are irreversible by design. Phishing, wrong-address sends, lost access, and contract bugs cause significant losses every year. Once confirmed, there is no undo.

REVERSO adds a time-locked reversibility layer on top of standard EVM transfers — letting senders cancel, recover, or auto-refund before finalization.

💡 The Solution

REVERSO introduces time-locked reversible transfers with up to 5 layers of protection:

┌─────────────────────────────────────────────────────────────────┐
│ 🔄 REVERSO TRANSFER FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ SEND ──▶ LOCK PERIOD ──▶ CLAIM WINDOW ──▶ COMPLETE │
│ │ │ │ │ │
│ │ [CANCEL OK] [RECIPIENT │ │
│ │ CLAIMS] │ │
│ │ │ │ │
│ └──────────────────────────┴───────────────┘ │
│ │
│ 🛡️ 5 LAYERS OF PROTECTION: │
│ ├── Layer 1: Cancel during lock period │
│ ├── Layer 2: Recovery Address 1 (hardware wallet) │
│ ├── Layer 3: Recovery Address 2 (exchange backup) │
│ ├── Layer 4: Auto-refund after expiry │
│ └── Layer 5: Rescue abandoned funds (90 days) │
│ │
│ 🏆 PREMIUM INSURANCE (+0.2%): │
│ └── Full refund even if scammer claims your funds! │
│ │
└─────────────────────────────────────────────────────────────────┘

✨ Features

🔒 Core Features

Feature	Description
Reversible Transfers	Cancel any transfer during lock period
Time-Lock Options	1 hour to 30 days - you choose
Triple Recovery	2 backup addresses + original sender
Auto-Refund	Unclaimed transfers return automatically
Multi-Token	ETH + any ERC-20 token
Multi-Chain	ETH, BSC, Base, Arbitrum, Polygon, Optimism, Avalanche — all live

💰 Progressive Fee Structure

Tier	Amount	Fee	Example
🏠 Retail	< $1,000	0.3%	$100 → $0.30 fee
💼 Standard	$1K - $100K	0.5%	$10,000 → $50 fee
🐋 Whale	> $100,000	0.7%	$1M → $7,000 fee

🛡️ Premium Insurance (+0.2%)

Pay 0.2% extra → Insurance coverage (subject to pool balance)
Even if scammer claims your funds:
├── You contact us with proof
├── We verify the scam
└── You get refunded from Insurance Pool 💰
Fully tested: payInsuranceClaim(), withdrawExcessInsurance(),
reject on non-insured transfer, reject on empty pool.
Example: 10 ETH with insurance
├── Base fee: 0.05 ETH (0.5%)
├── Insurance: 0.02 ETH (0.2%)
├── Total cost: 0.07 ETH (0.7%)
└── Protection: coverage subject to policy/pool ✓

🏢 Enterprise Payroll & Stipends (API)

Pay salaries, stipends and reimbursements with a lock window — cancel before the recipient claims if something goes wrong.
HMAC/nonce/timestamp API auth: keys stay server-side, no bearer tokens in frontend.
Recovery addresses and auto-refund: if the recipient doesn't claim, funds return automatically.
Optional insurance (+0.2%) to cover fraud or erroneous claims.
Rate limiting and audit-first rollout: mainnet gated until external audit is completed.

🌐 Supported Chains

Chain	Status	Chain ID
Ethereum	✅ Deployed & Verified	1
BSC	✅ Deployed	56
Base	✅ Deployed	8453
Arbitrum	✅ Deployed	42161
Polygon	✅ Deployed	137
Optimism	✅ Deployed	10
Avalanche	✅ Deployed	43114

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/Faraone-Dev/REVERSO.git
cd REVERSO
# Install dependencies
npm install
# Compile contracts
npx hardhat compile
# Run tests
npx hardhat run scripts/test-functions.ts --network hardhat
# Deploy locally
npx hardhat run scripts/deploy.ts --network hardhat
# Deploy to testnet
npx hardhat run scripts/deploy.ts --network sepolia
# Deploy multichain (uses hardhat config)
npx hardhat run scripts/deploy-multichain.ts

🚀 Ethereum Mainnet — Live Deployment

Full protocol stack deployed and verified on Ethereum Mainnet. All contracts are source-code verified on Etherscan, ownership has been transferred to the EmergencyGuardian multi-sig, and the monitoring layer is active.

📍 Production Contracts

Contract	Address	Etherscan	Role
🔐 ReversoVault	`0x31ec8EeeCb341c7cefAefA6BC0Dd84BE9Bd11085`	✅ Verified Source	Core vault — reversible transfers, fees, insurance
🛡️ EmergencyGuardian	`0x7F1CB513B7A582A11f3057F104D561E9A9126A7d`	✅ Verified Source	Multi-sig owner of Vault — timelock + emergency pause
👁️ ReversoMonitor	`0x152935935E86ab06ce75b6871c500f6Eb57f5332`	✅ Verified Source	Anomaly detection — auto-pause on critical alerts
💰 Treasury	`0x211a8C2d4f5924d4378162b48bC759a3E3e57dD8`	View	Receives protocol fees

🌐 Multi-Chain Deployments

Deployed February 24, 2026. Same 3-contract stack on every chain.

BSC (BNB Smart Chain)

Contract	Address
🔐 ReversoVault	`0x6Ec438bEfE7f956d115c4Aa2B9eB80996df4d322`
🛡️ EmergencyGuardian	`0x7C962938cce85737eB25147667279117f40dE23a`
👁️ ReversoMonitor	`0x1610DA56f09555a388AB8a095F180A2069FDA4F1`

Base

Contract	Address
🔐 ReversoVault	`0x1610DA56f09555a388AB8a095F180A2069FDA4F1`
🛡️ EmergencyGuardian	`0x038516Fd2EbF5AC7c6E4A85858CDaF908F4650C9`
👁️ ReversoMonitor	`0xA8854b60A3c150BA0b4FB7418eD7b15d577a129b`

Arbitrum

Contract	Address
🔐 ReversoVault	`0x6Ec438bEfE7f956d115c4Aa2B9eB80996df4d322`
🛡️ EmergencyGuardian	`0x7C962938cce85737eB25147667279117f40dE23a`
👁️ ReversoMonitor	`0x1610DA56f09555a388AB8a095F180A2069FDA4F1`

Polygon

Contract	Address
🔐 ReversoVault	`0x6Ec438bEfE7f956d115c4Aa2B9eB80996df4d322`
🛡️ EmergencyGuardian	`0x7C962938cce85737eB25147667279117f40dE23a`
👁️ ReversoMonitor	`0x1610DA56f09555a388AB8a095F180A2069FDA4F1`

Optimism

Contract	Address
🔐 ReversoVault	`0x6Ec438bEfE7f956d115c4Aa2B9eB80996df4d322`
🛡️ EmergencyGuardian	`0x7C962938cce85737eB25147667279117f40dE23a`
👁️ ReversoMonitor	`0x1610DA56f09555a388AB8a095F180A2069FDA4F1`

Avalanche (C-Chain)

Contract	Address
🔐 ReversoVault	`0x6Ec438bEfE7f956d115c4Aa2B9eB80996df4d322`
🛡️ EmergencyGuardian	`0x7C962938cce85737eB25147667279117f40dE23a`
👁️ ReversoMonitor	`0x1610DA56f09555a388AB8a095F180A2069FDA4F1`

🔗 Contract Wiring (On-Chain)

ReversoVault.owner() → EmergencyGuardian ✅
EmergencyGuardian.vault → ReversoVault ✅
ReversoMonitor.guardian → EmergencyGuardian ✅

Deploy Block:24520800 · Compiler: Solidity 0.8.20 · Optimizer: 200 runs

🌐 Testnet Deployment & Live Tests (Sepolia)

📍 Deployed Contracts

Contract	Address	Network	Status
ReversoVault v1	`0x2F5c8E09FBf360777153dd6F7F636077890e61DF`	Sepolia	✅ Verified
ReversoVault v2	`0x3D1f9d1cEaf350885A91f7Fb05c99a78Bc544ED8`	Sepolia	✅ Deployed
TestToken (TTK)	`0x72E847D973f9b215C7F561CD059CBd7a1601Fe3C`	Sepolia	✅ Verified
Treasury	`0x6a5729177bF2AE13351F43af0999767B59d9b059`	Sepolia	✅ Receives fees

Deploy Date: December 29, 2025

✅ Live Testnet Tests Passed

Test 1: sendETH() - Reversible Transfer Creation


TX Hash	`0x3176b0d6...`
Amount Sent	0.001 ETH
Amount After Fee	0.000997 ETH (0.3% fee)
Recipient	`0x...dEaD` (burn address for test)
Delay	1 hour
Memo	"Test REVERSO"
Gas Used	383,452
Status	✅ SUCCESS - Transfer created with status `Pending`

Test 2: cancel() - Reversal & Refund


TX Hash	`0x3c4fcf76...`
Transfer ID	1
Action	Cancel pending transfer
Gas Used	64,138
Result	✅ SUCCESS - Funds returned to sender, status changed to `Cancelled`

Test 3: sendETH() - Additional Transfer Test


TX Hash	`0x325757b3...`
Transfer ID	3
Gas Used	332,176
Status	✅ SUCCESS - Then cancelled to recover funds

Test 4: sendETHPremium() - Transfer with Insurance (+0.2%)


TX Hash	`0x824265692f...`
Transfer ID	4
Amount After Fees	0.000995 ETH (0.5% fee + 0.2% insurance)
Has Insurance	✅ `true`
Insurance Pool	Increased by +0.000002 ETH
Gas Used	358,128
Status	✅ SUCCESS - Premium transfer with insurance flag, then cancelled

Test 5: cancel() - Multiple Cancel Tests


Tested	Cancel on transfers #3 and #4
Gas Used	~64,000
Result	✅ SUCCESS - All cancelled transfers refunded correctly

Test 6: sendToken() - ERC20 Reversible Transfer


Token	TestToken (TTK) - `0x72E847D9...`
Vault	`0x3D1f9d1c...`
Approve TX	`0xac3168a9...`
sendToken TX	`0x3ecacf50...`
Amount	100 TTK
Gas Used	433,095
Cancel TX	`0x91d099ab...` (67,951 gas)
Status	✅ SUCCESS - ERC20 transfer created, cancelled, tokens refunded

📊 Test Summary

═══════════════════════════════════════════════════════════════
🌐 SEPOLIA TESTNET - LIVE TESTS
═══════════════════════════════════════════════════════════════
✅ Test 1: sendETH() → PASSED (383,452 gas)
└── 0.001 ETH sent with 1h delay, 0.3% fee collected
✅ Test 2: cancel() → PASSED (64,138 gas) └── Funds returned to sender, status = Cancelled
✅ Test 3: sendETH() → PASSED (332,176 gas)
└── Additional transfer test, cancelled to recover
✅ Test 4: sendETHPremium() → PASSED (358,128 gas)
└── Insurance flag set, pool increased +0.000002 ETH
✅ Test 5: cancel() → PASSED (multiple)
└── All pending transfers successfully cancelled
✅ Test 6: sendToken() → PASSED (433,095 gas)
└── ERC20 (TestToken) transfer + cancel working
✅ Test 7: claim() → PASSED (190,303 gas)
└── Recipient claimed after 1h unlock period!
═══════════════════════════════════════════════════════════════
7/7 TESTS PASSED ✅
═══════════════════════════════════════════════════════════════

Test 7: claim() - Recipient Claims After Unlock


TX Hash	`0x3e866e52...`
Vault	`0x3D1f9d1c...`
Transfer ID	2
Claimer	`0xb9279e38f6eab17f986E7133C60a46DE527628e3` (receiver wallet)
Amount Claimed	0.001994 ETH
Wait Time	1 hour (unlock period)
Gas Used	190,303
Status	✅ SUCCESS - Transfer status changed to `Claimed`, funds transferred to recipient

🔜 Pending Tests (Time-Dependent)

Test	Function	Description	Status
8	`refundExpired()`	Auto-refund after expiry	✅ Verified in Hardhat (ETH + ERC20)
9	`freezeTransfer()`	Guardian blocks suspicious transfer	✅ Verified in Hardhat (ETH + ERC20)
10	`rescueAbandoned()`	Rescue funds after 90+ days	✅ Verified in Hardhat (TVL consistent)

Note: Tests 8-10 are fully verified in local Hardhat tests (131 passing) including ERC20 lifecycle. On testnet they require real wait times.

🔑 Test Wallets

Wallet	Address	Purpose
Sender	`0x6a5729177bF2AE13351F43af0999767B59d9b059`	Deploys contracts, sends transfers
Receiver	`0xb9279e38f6eab17f986E7133C60a46DE527628e3`	Claims transfers (for claim() test)
Treasury	`0x6a5729177bF2AE13351F43af0999767B59d9b059`	Receives protocol fees

⚠️ Test Notes

claim(): Cannot send to self (_recipient != msg.sender check). Using 2nd wallet as recipient.
Time-dependent tests: Testnet doesn't allow time manipulation. Must wait real time.
rescueAbandoned(): Requires 90+ days - verified in local Hardhat tests only.

✅ Test Results (Verified)

Local Hardhat suite (ETH + ERC20 + insurance + rescue):

═══════════════════════════════════════════════════════════════
🧪 REVERSO - TEST RESULTS
═══════════════════════════════════════════════════════════════
TEST 1: CREATE TRANSFER (sendETH)
💸 Sending: 1 ETH
👤 To: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
⏱️ Delay: 1 hour
✅ Transfer created!
📋 Transfer ID: 1
💰 Amount after fee: 0.995 ETH (0.5% fee applied)
═══════════════════════════════════════════════════════════════
TEST 2: CANCEL TRANSFER
💰 Sender balance before: 9998.99 ETH
✅ Transfer CANCELLED!
💰 Sender balance after: 9999.99 ETH
🔙 Refunded: ~0.995 ETH ✓
═══════════════════════════════════════════════════════════════
TEST 3: CLAIM TRANSFER
💰 Recipient balance before: 10000.0 ETH
✅ Transfer CLAIMED!
💰 Recipient balance after: 10000.497 ETH
📊 Status: Claimed ✓
═══════════════════════════════════════════════════════════════
TEST 4: FEE COLLECTION
📊 Total Transfers: 2
🏦 Treasury received fees ✓
TEST 5: ERC20 TRANSFER
🔁 sendToken with fee tier
🏦 Treasury gets token fee
📈 TVL tracks token amount after fee
TEST 6: INSURANCE CLAIM
🛡️ sendETHPremium → claim → payInsuranceClaim
🏦 Insurance pool debits payout
👤 Victim receives compensation
TEST 7: RESCUE (TVL)
🧹 rescueAbandoned reduces TVL after late recovery
═══════════════════════════════════════════════════════════════
✅ ALL TESTS PASSED!
═══════════════════════════════════════════════════════════════

Verified Functions

Function	Status	Description
`sendETH()`	✅ Passed	Create reversible transfer with delay
`sendETHSimple()`	✅ Passed	Quick transfer with 24h default
`sendETHPremium()`	✅ Passed	Transfer with insurance (+0.2%)
`sendToken()`	✅ Passed	ERC20 transfer with fee-on-transfer support
`cancel()`	✅ Passed	Cancel and receive full refund (ETH + ERC20)
`claim()`	✅ Passed	Recipient claims after delay (ETH + ERC20)
`refundExpired()`	✅ Passed	Auto-refund after expiry (ETH + ERC20)
`batchRefundExpired()`	✅ Passed	Batch refund with DoS protection
`freezeTransfer()`	✅ Passed	Guardian freeze + refund (ETH + ERC20)
`manualRefund()`	✅ Passed	Owner manual refund for edge cases
`rescueAbandoned()`	✅ Passed	TVL-consistent late recovery
`payInsuranceClaim()`	✅ Passed	Insurance payout from pool
`withdrawExcessInsurance()`	✅ Passed	Excess pool withdrawal to treasury
`calculateFee()`	✅ Passed	Progressive fee tiers (retail/standard/whale)
`setCircuitBreakerLimits()`	✅ Passed	Circuit breaker configuration
`setAlertThreshold()`	✅ Passed	Alert threshold with bounds check
Fee Collection	✅ Passed	Treasury receives fees automatically

Basic Usage

// SIMPLE: Send with default 24h delay
reversoVault.sendETHSimple{value: 1ether}(
recipient, // address to receive"Payment #123"// optional memo
);
// ADVANCED: Custom delay, expiry, and DOUBLE recovery addresses
reversoVault.sendETH{value: 1ether}(
recipient, // address to receive6 hours, // delay before claim (min 1h, max 30d)30 days, // expiry - time to claim (min 7d)
ledgerAddr, // recovery address 1 (your hardware wallet)
coinbaseAddr, // recovery address 2 (your exchange)"Payment #123"// optional memo
);
// 🌟 PREMIUM: Full insurance coverage (recommended for large transfers)
reversoVault.sendETHPremium{value: 10ether}(
recipient, // address to receive7 days, // delay30 days, // expiry
ledgerAddr, // recovery 1
coinbaseAddr, // recovery 2"Large payment"// memo
);
// Pays: 0.5% base + 0.2% insurance = 0.7% total// Gets: Scam/theft coverage from insurance pool// Cancel before delay expires (FREE!)
reversoVault.cancel(transferId);
// Claim after delay (recipient calls)
reversoVault.claim(transferId);
// Refund expired transfer (anyone can call after expiry)
reversoVault.refundExpired(transferId);
// Rescue abandoned funds (anyone can call after 90 days post-expiry)
reversoVault.rescueAbandoned(transferId);

Delay Options

Delay	Best For
1 hour	Urgent but want minimal protection
6 hours	Daily transactions
24 hours	Standard protection (DEFAULT)
7 days	Large amounts
30 days	Escrow, major purchases

🔌 Enterprise API

REST API for programmatic access to reversible transfers.

Base URL

Production: https://reverso-tu3o.onrender.com/api/v1
Development: http://localhost:3000/api/v1

Authentication

curl -H "Authorization: Bearer rsk_business_xxx..." \
https://reverso-tu3o.onrender.com/api/v1/transfers

Quick Example

// 1. Register for API keyconstregister=awaitfetch('/api/v1/auth/register',{method: 'POST',headers: {'Content-Type': 'application/json'},body: JSON.stringify({email: 'dev@company.com',password: 'secure123',company: 'Acme Inc',plan: 'business'})});const{ apiKey }=awaitregister.json();// ⚠️ Save apiKey.key - shown only once!// 2. Create reversible transferconsttransfer=awaitfetch('/api/v1/transfers',{method: 'POST',headers: {'Authorization': `Bearer ${apiKey.key}`,'Content-Type': 'application/json'},body: JSON.stringify({chainId: 1,// Ethereumto: '0x...',// Recipientamount: '1000000000000000000',// 1 ETH in weiwithInsurance: true// +0.2% for full protection})});const{ transaction }=awaittransfer.json();// Sign `transaction` with ethers.js and broadcast!

API Endpoints

Method	Endpoint	Description
`POST`	`/auth/register`	Create account & get API key
`POST`	`/auth/login`	Login existing user
`POST`	`/auth/quick-key`	Instant API key (email only)
`GET`	`/auth/plans`	List subscription plans
`POST`	`/auth/verify-email/send`	Send verification email (JWT)
`GET`	`/auth/verify-email?token=`	Verify email address
`POST`	`/auth/forgot-password`	Request password reset
`POST`	`/auth/reset-password`	Set new password with token
`POST`	`/transfers`	Create reversible transfer
`GET`	`/transfers/:id`	Get transfer status
`GET`	`/transfers`	List all transfers
`POST`	`/transfers/:id/cancel`	Generate cancel transaction
`POST`	`/transfers/:id/confirm`	Confirm after blockchain tx
`POST`	`/usecases/checkout`	E-commerce checkout flow (Enterprise)
`POST`	`/usecases/payroll`	Batch payroll (Enterprise)
`POST`	`/usecases/escrow`	Escrow transfer (Enterprise)
`GET`	`/webhooks`	List webhooks (Business+)
`POST`	`/webhooks`	Create webhook (Business+)
`PATCH`	`/webhooks/:id`	Update webhook (Business+)
`DELETE`	`/webhooks/:id`	Delete webhook (Business+)
`POST`	`/webhooks/:id/test`	Send test event (Business+)
`GET`	`/admin/usage`	View API usage (Business+)
`GET`	`/admin/stats`	Real-time analytics from SQLite (Enterprise)
`GET`	`/admin/denylist`	List blocked addresses (Enterprise)
`POST`	`/admin/denylist`	Block address (Enterprise)
`DELETE`	`/admin/denylist/:addr`	Unblock address (Enterprise)
`PUT`	`/admin/branding`	White-label config (Enterprise)
`GET`	`/admin/sla`	SLA status (Enterprise)
`GET`	`/admin/export`	Export transfer data (Business+)

Webhooks

Receive real-time notifications for transfer events:

{
"type": "transfer.claimed",
"data": {
"id": "uuid",
"txHash": "0x...",
"from": "0x...",
"to": "0x...",
"amount": "1000000000000000000",
"status": "claimed"
},
"createdAt": "2025-12-26T12:00:00Z"
}

Available Events:

transfer.created - New transfer created
transfer.claimed - Recipient claimed funds
transfer.cancelled - Sender cancelled transfer
transfer.refunded - Expired transfer refunded

Run API Locally

cd api
npm install
cp .env.example .env
npm run dev
# Server runs on http://localhost:3000

API Security (HMAC)

All protected endpoints require these headers:

Authorization: Bearer <apiKey>
x-reverso-timestamp: Epoch milliseconds (±5 minutes tolerance)
x-reverso-nonce: Unique UUID to prevent replay attacks
x-reverso-signature: HMAC-SHA256 of timestamp.nonce.METHOD.URL.sha256(body) signed with signingSecret

Rate Limiting: 300 req/min per API key + transaction limit per plan.

Multi-Chain Configuration

Config source: api/config/chains.json + .env variables for RPC and vault addresses
After deployment, update .env with actual contract addresses

Transaction Encoding

// ETH transferssendETH(recipient, delay, expiryPeriod, recovery1, recovery2, memo)
// ERC20 transfers sendToken(token, recipient, amount, delay, expiryPeriod, recovery1, recovery2, memo)

Note: Memo max 256 characters; recovery addresses cannot be zero address.


---
## 🔐 Security
### Security Architecture (3-Contract System)
REVERSO uses a **3-layer security architecture**:

┌─────────────────────────────────────────────────────────────────┐ │ 🏗️ REVERSO SECURITY STACK │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ 👁️ ReversoMonitor │ │ │ │ • Anomaly detection (volume spikes, suspicious tx) │ │ │ │ • Auto-pause on CRITICAL alerts │ │ │ │ • Watchlist management │ │ │ │ • Chainlink Automation compatible │ │ │ └─────────────────────┬───────────────────────────────────┘ │ │ │ triggers │ │ ┌─────────────────────▼───────────────────────────────────┐ │ │ │ 🛡️ EmergencyGuardian │ │ │ │ • Multi-signature (2-of-2 for critical actions) │ │ │ │ • 24-hour timelock on admin changes │ │ │ │ • Instant emergency pause │ │ │ │ • Recovery system with dual confirmation │ │ │ └─────────────────────┬───────────────────────────────────┘ │ │ │ owns │ │ ┌─────────────────────▼───────────────────────────────────┐ │ │ │ 🔐 ReversoVault │ │ │ │ • Core reversible transfer logic │ │ │ │ • 5-layer user protection │ │ │ │ • Progressive fees + insurance │ │ │ │ • Circuit breaker │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘


### Contract Details
| Contract | Lines | Purpose |
|----------|-------|---------|
| **ReversoVault.sol** | 1,119 | Core vault - reversible transfers, fees, insurance |
| **EmergencyGuardian.sol** | 401 | Multi-sig owner, timelock, emergency controls |
| **ReversoMonitor.sol** | 320 | Real-time monitoring, anomaly detection, auto-pause |
### EmergencyGuardian Features
```solidity
// 🚨 INSTANT - Any guardian can pause immediately
guardian.emergencyPause("Suspicious activity detected");
// ⏱️ TIMELOCK - Critical actions need 24h + dual confirmation
guardian.proposeAction(ActionType.CHANGE_TREASURY, newTreasury);
// ... 24 hours later, DIFFERENT guardian confirms ...
guardian.confirmAction(actionId);
guardian.executeAction(actionId);
// 🔐 MULTI-SIG - Two keys required for sensitive operations
// Primary key: Hot wallet (daily operations)
// Secondary key: Hardware wallet (backup, confirms critical actions)

ReversoMonitor Features

// 📊 Automatic anomaly detection
monitor.recordTransaction(sender, amount);
// Triggers alerts on:// - Single tx > 50 ETH (HIGH alert)// - Hourly volume > 100 ETH (HIGH alert) // - Hourly volume > 200 ETH (CRITICAL → auto-pause)// - Watchlisted address activity (MEDIUM alert)// 🤖 Chainlink Automation compatible
(boolupkeepNeeded, bytesmemorydata) = monitor.checkUpkeep("");

Smart Contract Security

✅ ReentrancyGuard on all external functions
✅ Pausable for emergency stops
✅ Circuit breaker (auto-pause on suspicious activity)
✅ Timelock on admin changes (24 hours via Guardian)
✅ Multi-signature for critical operations
✅ Guardian system for freezing suspicious transfers
✅ OpenZeppelin battle-tested contracts
✅ Anomaly detection with auto-pause

Web & API Security

Protection	Layer	Description
Content Security Policy	Website	Strict CSP blocking unauthorized scripts, iframes, and connections
X-Content-Type-Options	Website	Prevents MIME-type sniffing attacks
Referrer Policy	Website	Controls information leakage to external sites
Frame-ancestors: none	Website	Anti-clickjacking — prevents iframe embedding
Upgrade-insecure-requests	Website	Forces HTTPS on all resources
XSS Sanitizer	Website	`escapeHtml()` on all user-interpolated data
CORS Lockdown	API	Restricted to `reverso.one` only (no wildcard)
Helmet.js	API	HSTS (1 year + preload), CSP, referrer policy
HMAC-SHA256	API	Request signature verification with timestamp + nonce
Replay Protection	API	Nonce-based deduplication prevents replay attacks
Rate Limiting	API	Global: 1000 req/15min — Per-key: 300 req/min
Bcrypt (10 rounds)	API	Industry-standard hashing for API key credentials
JWT Auth	API	30-day token expiry with strong secret
Error Masking	API	500 errors masked in production, no path leakage
Input Validation	API	Email regex, address regex, amount checks

5-Layer User Protection System

Layer 1: CANCEL
├── Sender can cancel anytime during lock period
└── 100% refund, zero questions asked
Layer 2: RECOVERY ADDRESS 1
├── If sender loses access, funds go here
└── Recommended: Hardware wallet (Ledger, Trezor)
Layer 3: RECOVERY ADDRESS 2
├── If recovery 1 fails, try recovery 2
└── Recommended: Exchange account (Coinbase, Binance)
Layer 4: AUTO-REFUND
├── If recipient never claims, auto-refund after expiry
└── Anyone can trigger (gas incentive)
Layer 5: RESCUE
├── After 90 days post-expiry, rescue abandoned funds
└── Tries all 3 addresses, then treasury for manual handling

Audit Status

🔒 Security First Approach — Mainnet Live

Smart contract follows OpenZeppelin best practices
ReentrancyGuard, Pausable, SafeERC20 implemented

Current Status:

✅ Ethereum Mainnet deployed (all 3 contracts verified on Etherscan)
✅ 7 chains live — Ethereum, BSC, Base, Arbitrum, Polygon, Optimism, Avalanche
✅ Testnet validation completed (Sepolia — 7/7 live tests passed)
✅ 163 tests passing (131 Hardhat + 32 API Jest — HMAC, validation, denylist, plans)
✅ 13,000+ Foundry fuzz runs (13 property-based tests × 1,000 random inputs each)
✅ Slither static analysis (143 items reviewed, 0 true-positive criticals)
✅ Gas benchmarks — all operations within L2-friendly limits
✅ Website live at reverso.one
✅ Enterprise API live at reverso-tu3o.onrender.com
🔜 External audit planned (not yet scheduled)

Bug Bounty

If you find a security vulnerability, please report it responsibly via GitHub Issues or email. Severity-based rewards will be evaluated on a case-by-case basis.

Insurance Policy

Transfers sent with hasInsurance = true are eligible for coverage from the insurance pool if funds are claimed by a confirmed scammer. Coverage is subject to pool balance and requires evidence submission within 30 days.

📁 Project Structure

REVERSO/
├── 📁 contracts/ # Solidity smart contracts
│ ├── ReversoVault.sol # Core vault (1,119 lines)
│ ├── EmergencyGuardian.sol # Multi-sig guardian (401 lines)
│ ├── ReversoMonitor.sol # Anomaly detection (320 lines)
│ └── interfaces/
│ └── IReversoVault.sol # Contract interface
├── 📁 test/ # Test suites (131 Hardhat tests)
│ ├── ReversoVault.test.ts # Vault tests (68 tests)
│ ├── SecurityContracts.test.ts # Guardian + Monitor tests (48 tests)
│ └── GasBenchmarks.test.ts # Gas benchmarks (15 tests)
├── 📁 api/ # Enterprise REST API
│ ├── src/
│ │ ├── index.ts # Express server
│ │ ├── routes/ # Transfer, auth, webhooks, admin, usecases, billing
│ │ ├── middleware/ # HMAC, rate limiting, API keys
│ │ └── utils/ # Fraud denylist (file + env + runtime)
│ ├── test/ # API tests (32 Jest tests)
│ ├── sdk/ # TypeScript SDK with HMAC signing
│ └── config/ # Multi-chain configuration
├── 📁 website/ # Production website (Vite)
│ ├── src/
│ │ ├── main.js # App logic
│ │ └── styles/ # CSS
│ └── index.html # Entry point
├── 📁 keeper/ # Keeper bot (WebSocket + Monitor)
│ └── src/index.ts # Event listener, reconnection, stats
├── 📁 scripts/ # Deploy scripts
│ ├── deploy.ts # Single chain deploy
│ ├── deploy-stack.ts # Full 3-contract deploy + wiring
│ └── deploy-multichain.ts # Multi-chain deploy
├── 📁 security/ # Security suite
│ ├── foundry-fuzz/ # Foundry fuzz tests (13,000+ runs)
│ ├── slither/ # Static analysis reports
│ └── gas-benchmarks/ # Gas profiling
├── 📄 .github/workflows/ci.yml # CI pipeline (contracts + API + website)
├── 📄 hardhat.config.ts # Multi-chain configuration (15+ chains)
└── 📄 README.md # This file

️ Roadmap

Phase 1: Foundation (Q4 2025) ✅

Phase 2: Launch (Q1 2026) ✅

🛠️ Development

Prerequisites

Node.js 18+
npm or yarn
Git

Setup

# Clone repo
git clone https://github.com/Faraone-Dev/REVERSO.git
cd REVERSO
# Install dependencies
npm install
# Setup environment
cp .env.example .env
# Edit .env with your keys# Compile
npx hardhat compile
# Test
npx hardhat test# Coverage
npx hardhat coverage
# Deploy
npx hardhat run scripts/deploy.ts --network sepolia

Environment Variables

# RequiredPRIVATE_KEY=your-deployer-private-keyETHERSCAN_API_KEY=your-etherscan-key# Optional (for multi-chain)ARBISCAN_API_KEY=BASESCAN_API_KEY=OPTIMISM_API_KEY=POLYGONSCAN_API_KEY=

⚠️ Current Status & Limitations

Transparency note: REVERSO is a production-grade MVP. The sections below describe what is fully shipped and what is still in development.

Component	Status	Notes
Smart Contracts	✅ Production	Deployed on 7 chains, verified on Etherscan, immutable
Hardhat Tests	✅ 131 passing	Full coverage of vault, guardian, monitor
API Tests	✅ 32 passing	HMAC, error handlers, validation, denylist logic, plan features
Foundry Fuzz Tests	✅ 13,000+ runs	Invariant + property-based
HMAC + Replay Protection	✅ Production	SHA-256, nonce DB, 60s drift window
Webhook Delivery	✅ Real POST	Exponential backoff retry (3 attempts, 1s/2s/4s), auto-disable after 10 failures
Fraud Denylist	✅ File + Env + API	Hot-reloaded every 60s, admin CRUD endpoints, persisted to JSON
Admin Stats	✅ Real SQLite	`byStatus`, `byChain`, `successRate`, insurance aggregation
Email Verification	✅ Production	Token-based, 24h expiry, Resend integration
Password Reset	✅ Production	SHA-256 hashed tokens, 1h expiry, anti-enumeration
Usecase Persistence	✅ SQLite	Checkout/payroll/escrow persist to DB (not in-memory)
CI/CD	✅ GitHub Actions	Contracts compile+test, API type-check+test, website build
Stripe Billing	✅ Production	Checkout sessions, webhook signature verification, plan upgrades
SDK	✅ Production	TypeScript SDK with HMAC signing, full CRUD
Keeper Bot	✅ Code complete	WebSocket listener, Monitor integration, reconnection logic
Database	🟡 SQLite (WAL)	Good for MVP; migration to PostgreSQL recommended at scale
White-Label	🟡 Placeholder	Endpoints exist, config not persisted to DB
SLA Reporting	🟡 Placeholder	Returns static values, no real uptime tracking yet
Email Delivery	🟡 Optional	Requires `RESEND_API_KEY`; gracefully skipped when absent

📜 License

MIT License - see LICENSE

🔗 Links

Resource	Link
🌐 Website	reverso.one
🔌 API (Live)	reverso-tu3o.onrender.com
📦 Repository	github.com/Faraone-Dev/REVERSO
📄 Documentation	This README
🔌 API Docs	Enterprise API Section

🚀 What's Included

REVERSO/
├── 📁 contracts/ # 3 Solidity smart contracts (1,840 lines total)
│ ├── ReversoVault.sol # Core vault with 5-layer protection
│ ├── EmergencyGuardian # Multi-sig + timelock + emergency pause
│ ├── ReversoMonitor # Anomaly detection + auto-pause
│ └── interfaces/ # Contract interfaces
├── 📁 test/ # Hardhat test suite (131 tests)
├── 📁 security/ # Security suite (Foundry fuzz 13,000+ runs + Slither)
├── 📁 api/ # Enterprise REST API (32 API tests)
│ ├── src/routes/ # Transfer, auth, webhooks, admin, usecases, billing
│ ├── src/middleware/ # HMAC, rate limiting, API keys
│ ├── src/utils/ # Fraud denylist (file + env + runtime)
│ └── sdk/ # TypeScript SDK with HMAC signing
├── 📁 website/ # Production website (Vite + vanilla JS)
├── 📁 scripts/ # Deploy scripts (single & multi-chain)
├── 📄 README.md # This file
└── 📄 hardhat.config.ts # Multi-chain configuration (15+ chains)

🔧 Deployment

One-Command Full Stack Deploy

# Deploy all 3 contracts + wire them together automatically
npx hardhat run scripts/deploy-stack.ts --network ethereum

This script performs all 6 steps automatically:

Deploy ReversoVault (treasury address from .env)
Deploy EmergencyGuardian (secondary guardian from .env)
vault.transferOwnership(guardian) — guardian becomes vault owner
guardian.linkVault(vault) — guardian knows which vault to protect
Deploy ReversoMonitor (vault address as constructor arg)
monitor.setGuardian(guardian) — monitor can trigger guardian alerts

Manual Step-by-Step

# 1. Deploy ReversoVault
npx hardhat run scripts/deploy.ts --network ethereum
# 2-6. The deploy-stack.ts script handles wiring automatically.# See scripts/deploy-stack.ts for the full deployment flow.

🛡️ Deployed on Ethereum Mainnet — All Contracts Verified on Etherscan

ReversoVault · EmergencyGuardian · ReversoMonitor

131 Hardhat + 32 API tests passing · 3-contract security stack · Enterprise REST API

Built with ❤️ for a safer crypto future

REVERSO Protocol — Because everyone deserves a second chance.

Name		Name	Last commit message	Last commit date
Latest commit History 99 Commits
.github/workflows		.github/workflows
api		api
contracts		contracts
docs		docs
keeper		keeper
scripts		scripts
security		security
test		test
website		website
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
.npmrc		.npmrc
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
foundry.lock		foundry.lock
foundry.toml		foundry.toml
hardhat.config.ts		hardhat.config.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation