feat(contracts): implement meta-tx replay attack protection with EIP-712

[OG-wura]

Close #176

Pull Request Document

Meta-TX Replay Attack Protection Implementation

🎯 Summary

Implements comprehensive replay attack prevention for meta-transaction handling in TruthBounty contracts. Adds EIP-712 signature verification, per-user nonce tracking, and multi-layer replay protection mechanisms.

Related Issue: #CO-176

---

📝 Description

Problem

The original MetaTxExample contract lacked replay attack protection, allowing:

• Same transaction to be executed multiple times with identical signature
• Signatures from one chain to be replayed on another chain
• Old signatures to be executed after nonce changes
• No time-bound validation on transaction validity

Solution

Implemented multi-layer replay attack prevention using:

1. Per-User Nonce System (mapping(address => uint256))

   • Each user maintains independent incrementing nonce
   • Nonce included in EIP-712 signature
   • Prevents reusing old signatures

2. Used Signature Tracking (mapping(bytes32 => bool))

   • Tracks executed signature digests
   • Prevents exact replay of executed transactions
   • Additional defense layer after nonce validation

3. Chain ID in Domain Separator

   • EIP-712 domain includes current chain ID
   • Different chains produce different domain separators
   • Prevents cross-chain signature reuse

4. Deadline Validation

   • Signatures include expiration timestamp
   • Rejects signatures after deadline
   • Time-bounds transaction validity

---

🔧 Changes

Smart Contracts

contracts/MetaTxExample.sol

• Added EIP712 contract inheritance
• Added nonces mapping for per-user replay protection
• Added usedSignatures mapping for signature digest tracking
• Added TRANSFER_TYPEHASH constant for EIP-712
• Implemented executeTransfer() with:
  • Deadline validation
  • EIP-712 signature verification
  • Nonce checking
  • Used signature tracking
  • Nonce incrementation after execution
• Added getNonce() and getDomainSeparator() getters
• Enhanced input validation in _executeTransfer()

Service Layer

meta-tx/meta-tx.service.ts

• Refactored to support EIP-712 signature verification
• Implemented prepareTransfer() for structured data preparation
• Implemented verifySignature() for signature validation
• Implemented relayTransaction() with proper validation
• Added getNonce() and isSignatureUsed() getters
• Comprehensive error handling and validation
• Environment variable validation in constructor

meta-tx/meta-tx.controller.ts

• Added three endpoints:
  • POST /meta-tx/relay - Relay meta-transaction
  • POST /meta-tx/nonce - Get current user nonce
  • POST /meta-tx/prepare - Prepare transfer data for signing
• Implemented comprehensive input validation:
  • Address format validation
  • Amount validation (> 0)
  • Deadline validation (future timestamp)
  • Signature format validation
• Improved error messages and response structure

Tests

test/MetaTxExample.test.ts (New - 22 tests)

• Domain separator and nonce initialization (3 tests)
• Signature verification and execution (3 tests)
• Replay attack prevention (4 tests)
• Cross-chain replay protection (2 tests)
• ERC2771Context integration (1 test)
• Transfer function validation (2 tests)
• Nonce management (7 tests)

meta-tx/tests/meta-tx.service.spec.ts (Updated - 16 tests)

• Constructor and environment validation (3 tests)
• Signature verification (3 tests)
• Nonce management (1 test)
• Replay attack prevention (2 tests)
• Input validation (2 tests)
• Error handling (5 tests)

test/fuzz/MetaTxReplayAttackFuzz.sol (New - 11 tests)

• Nonce increment invariants
• Signature replay prevention invariants
• Domain separator consistency
• Parameter validation invariants
• Property-based tests for signature recovery
• Independent nonce management properties

---

✅ Acceptance Criteria

• Implementation is functional

  • EIP-712 domain separator correctly generated
  • Nonce system properly tracks per-user state
  • Signatures properly verified before execution
  • Multi-layer replay prevention in place

• Tests passed

  • 22 unit tests for MetaTxExample
  • 16 service tests for meta-tx operations
  • 11 invariant/fuzz tests
  • All test categories passing

• No regressions

  • ERC2771Context integration preserved
  • Transfer function maintains backward compatibility
  • No breaking changes except executeTransfer() signature

---

🧪 Testing

Run Unit Tests

npm test test/MetaTxExample.test.ts
npm test meta-tx/tests/meta-tx.service.spec.ts

Run Fuzz Tests

forge test --match-contract MetaTxReplayAttackFuzz -vv
forge test --match-contract MetaTxReplayAttackFuzz --fuzz-runs 1000 -vv

Test Coverage Summary

Category	Tests	Status
MetaTxExample unit tests	22	✅ PASS
Service tests	16	✅ PASS
Fuzz/invariant tests	11	✅ PASS
Total	49+	✅ ALL PASS

---

🔐 Security Review

Replay Attack Prevention

• ✅ Nonce-based: Each transaction includes unique nonce
• ✅ Signature digest tracking: Used signatures stored and checked
• ✅ Domain separator: Includes chainId for chain-specificity
• ✅ Deadline: Signatures expire after specified timestamp

Signature Verification

• ✅ EIP-712 compliant: Uses proper typed data hashing
• ✅ ECDSA recovery: Correctly recovers signer address
• ✅ Signature validation: Rejects mismatched signatures
• ✅ Expiration checks: Rejects expired deadlines

Input Validation

• ✅ Address validation: Rejects zero addresses
• ✅ Amount validation: Rejects zero amounts
• ✅ Deadline validation: Ensures deadline is in future
• ✅ Signature format: Validates hex string format

---

📊 Files Changed

File	Type	Changes
MetaTxExample.sol	Smart Contract	Enhanced with EIP712 + nonce + signature verification
MetaTxExample.test.ts	Test	New comprehensive unit tests (22 tests)
meta-tx.service.ts	Service	Updated with EIP-712 implementation
meta-tx.controller.ts	API	Enhanced with validation and new endpoints
meta-tx.service.spec.ts	Test	Updated service tests (16 tests)
MetaTxReplayAttackFuzz.sol	Test	New fuzz/invariant tests (11 tests)

---

🚀 Integration Guide

For Smart Contract Developers

1. Import and inherit from both ERC2771Context and EIP712
2. Maintain nonces and usedSignatures mappings
3. Implement signature verification in protected functions
4. Increment nonce after successful execution

For dApp Developers

// 1. Get current nonce
const nonce = await metaTxService.getNonce(userAddress);

// 2. Prepare transfer data
const { domain, types, value } = await metaTxService.prepareTransfer(
  userAddress, recipientAddress, amount, deadline
);

// 3. Sign with user's wallet
const signature = await userWallet.signTypedData(domain, types, value);

// 4. Relay transaction
const result = await metaTxService.relayTransaction(
  userAddress, recipientAddress, amount, deadline, signature
);

For API Users

# 1. Prepare transfer
POST /meta-tx/prepare
{
  "from": "0x...",
  "to": "0x...",
  "amount": "1000000000000000000",
  "deadline": 1234567890
}

# 2. Sign locally (in user's wallet/app)

# 3. Relay transaction
POST /meta-tx/relay
{
  "from": "0x...",
  "to": "0x...",
  "amount": "1000000000000000000",
  "deadline": 1234567890,
  "signature": "0x..."
}

---

📚 Documentation

• Detailed implementation guide: META_TX_IMPLEMENTATION.md
• Quick reference: META_TX_QUICK_REFERENCE.md
• Test cases show practical usage examples

---

⚠️ Breaking Changes

• executeTransfer() signature changed from executeMetaTx(requestData, signature) to executeTransfer(from, to, amount, deadline, signature)
• Requires migration of existing relayer implementations
• See integration guide above for updated patterns

---

✨ Future Improvements

• Consider batch transfer execution for gas optimization
• Add signature expiry event emissions for better tracking
• Implement signature revocation mechanism
• Support for delegated nonce management

---

📋 Checklist

• Code compiles without errors
• All tests pass (49+ tests)
• No regressions detected
• Code follows project standards
• Comments and documentation added
• Breaking changes documented
• Integration guide provided
• Security review completed

---