Skip to content

feat: Phase 2 - Ethereum Escrow via IBC Eureka#18

Open
zmanian wants to merge 13 commits into
feature/phase1-eureka-integrationfrom
feature/phase2-ethereum-escrow
Open

feat: Phase 2 - Ethereum Escrow via IBC Eureka#18
zmanian wants to merge 13 commits into
feature/phase1-eureka-integrationfrom
feature/phase2-ethereum-escrow

Conversation

@zmanian
Copy link
Copy Markdown
Contributor

@zmanian zmanian commented Jan 5, 2026 •
edited
Loading

Summary

  • Enable Ethereum users to escrow funds via IBC Eureka - solvers front Cosmos-side funds and take settlement risk
  • Add settlement risk pricing model - bond multipliers, failure probability, expected value calculations for solver fronting decisions
  • Implement packet monitoring infrastructure - EurekaPacketMonitor trait for tracking Eureka packet status and ZK proof finality
  • Full escrow contract implementation - all 6 Ethereum escrow handlers with state machine and tests
  • Comprehensive adversarial testing - 21 tests covering economic and security attack vectors

Design Alignment with Skip Go Fast

This implementation follows Skip Go Fast design principles:

  • Intent-based execution with solver fronting
  • Solver takes settlement risk, posts bond as collateral
  • Timeout guarantees - failed escrows return bonds
  • Verification before settlement - ZK proof finality required before claim

Key difference: Two-stage finality (Received → Finalized) for IBC Eureka's ZK proof architecture.

Changes

Types (crates/types)

  • EscrowStatus enum: Pending → Received → Finalized/Failed state machine
  • EthereumEscrowedIntent: Intent with Ethereum-side escrow metadata
  • SettlementRiskPricing: Bond multiplier, failure probability (risk premium auction-discovered)
    • default_ethereum_l1(): 20 min finality, 1.5x bond
    • default_op_stack_l2(): 20 min finality (Base, Optimism)
    • default_zk_rollup(): 15 min finality
  • FrontingRiskAssessment: Should-front decision with expected value calculation
  • EurekaPacketStatus: NotFound/Pending/Finalized/Failed packet states

Escrow Contract (contracts/escrow)

State Storage:

  • EthereumEscrow struct with full lifecycle tracking
  • EthereumEscrowStatus enum (Pending/Received/Finalized/Fronted/Claimed/Failed)
  • FrontingInfo for solver fronting details (solver_id, bond_amount, output_amount)

Handlers (all implemented):

  • RegisterEthereumEscrowIntent: Register intent with pending Eureka escrow
  • NotifyEurekaPacketReceived: Relayer notifies packet arrival, validates sender
  • NotifyEurekaFinalized: ZK proof verified, funds ready for claim
  • FrontSettlement: Solver fronts funds with explicit risk bond
  • ClaimEurekaEscrow: Release escrowed funds + bond to solver after finality
  • HandleEurekaEscrowFailure: Handle timeout/failure, return bond to solver

Error Types:

  • InvalidEthereumEscrowStatus, EthereumSenderMismatch, EurekaTimeout
  • PacketIdMismatch, NotFronted, InsufficientBond

Relayer (crates/relayer)

  • EurekaPacketMonitor async trait for packet tracking
  • MockEurekaMonitor for testing with configurable delays/failures

Solver (crates/solver)

  • can_front_settlement(): Check if solver can front for escrowed intent
  • calculate_fronting_bond(): Compute required bond amount
  • assess_fronting(): Full risk assessment with expected value
  • Builder methods: with_fronting(), with_risk_pricing()

Tests

Escrow Contract Tests: 89 total

  • 29 unit tests (lock, release, refund, config)
  • 24 adversarial tests (existing escrow attacks)
  • 15 Ethereum escrow handler tests
  • 21 adversarial Ethereum escrow tests (economic + security attacks)

Adversarial Coverage:

  • Economic: Griefing, front-running, claim theft, bond extraction, timeout manipulation
  • Security: Replay protection, sender spoofing, unauthorized access, double claim, wrong state

Documentation

  • docs/ETHEREUM_ESCROW_TESTING_PLAN.md: Comprehensive 5-level testing plan

Test Plan

  • All 89 escrow contract tests passing
  • All workspace tests passing
  • Clippy clean
  • Cargo fmt applied
  • Escrow contract handlers fully implemented
  • Adversarial tests for economic and security attacks
  • Design compared with Skip Go Fast principles
  • Integration test with actual Eureka testnet (future)

Dependencies

This PR depends on Phase 1 (#17) - Eureka Integration for solver liquidity sourcing.

🤖 Generated with Claude Code

zmanian and others added 13 commits January 5, 2026 13:35
@zmanian @claude
feat(types): add EscrowStatus and EthereumEscrowedIntent types
580fb78 
Phase 2 Ethereum escrow types:
- EscrowStatus: Pending, Received, Finalized, Failed
- EthereumEscrowedIntent: Intent wrapper with ETH sender and escrow status
- Lifecycle methods: is_pending, is_ready_for_fronting, is_finalized
- State transitions: mark_received, mark_finalized, mark_failed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
feat(types): add SettlementRiskPricing for Eureka fronting
1c1a0d5 
Settlement risk types for solver fronting:
- SettlementRiskPricing: failure probability, bond multiplier, risk premium
- required_bond(): calculate bond for fronted amount
- adjust_quote(): apply risk premium to output
- FrontingRiskAssessment: expected value calculation for fronting decisions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
feat(types): add EurekaPacketStatus and MonitorError types
243e0ff 
Eureka packet monitoring types:
- EurekaPacketStatus: NotFound, Pending, Finalized, Failed
- EurekaPacketInfo: detailed packet information
- MonitorError: errors for packet monitoring operations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
feat(relayer): add EurekaPacketMonitor trait and mock
6b7437c 
Eureka packet monitoring:
- EurekaPacketMonitor trait with async methods
- MockEurekaMonitor for testing
- watch_for_packet, get_packet_status, verify_finality, get_packet_info
- Packet lifecycle simulation for tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
feat(escrow): add Ethereum escrow messages
d76c60f 
New execute messages for Ethereum escrow:
- RegisterEthereumEscrowIntent
- NotifyEurekaPacketReceived
- NotifyEurekaFinalized
- FrontSettlement
- ClaimEurekaEscrow
- HandleEurekaEscrowFailure

New query: EthereumEscrowStatus

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
feat(solver): add fronting capability to EurekaSolver
313f5af 
EurekaSolver fronting for Ethereum-escrowed intents:
- can_front_settlement() check
- calculate_fronting_bond() with risk multiplier
- assess_fronting() with expected value calculation
- get_fronting_quote() with risk premium
- Builder methods: with_fronting(), with_risk_pricing()

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
test(solver): add Ethereum escrow integration tests
56dbc0c 
Integration tests for Phase 2 Ethereum escrow flow:
- Intent creation and lifecycle
- Solver fronting setup and configuration
- Bond calculation and risk assessment
- Custom risk pricing
- Failure handling
- Quote adjustment

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
chore: final verification and cleanup for Phase 2
40d120a 
- Fix formatting issues across multiple files
- Ensure all lib.rs exports are correct
- All 683 tests passing
- Clippy clean with -D warnings

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
refactor: simplify risk pricing - auction discovers premiums
6f2a567 
- Remove risk_premium_bps field from SettlementRiskPricing
- Remove adjust_quote and get_fronting_quote methods
- Risk premiums are now auction-discovered (solvers bid total spread)
- Protocol only enforces bond requirements (1.5x default, 2x conservative)
- Update finality times: Ethereum L1 20min, OP Stack 20min, ZK rollups 15min
- Add source-specific presets: default_ethereum_l1, default_op_stack_l2, default_zk_rollup

Key insight: Solvers compete on price in the auction. Their bid implicitly
includes their risk assessment. The protocol only needs to enforce bond
requirements for collateral, not compute risk premiums.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
feat: implement Ethereum escrow contract handlers via Eureka
8032caa 
Add complete implementation for Ethereum escrow handling through
IBC Eureka with ZK proof finality:

State storage:
- EthereumEscrow struct with full lifecycle tracking
- EthereumEscrowStatus enum (Pending/Received/Finalized/Fronted/Claimed/Failed)
- FrontingInfo for solver fronting details

Contract handlers:
- RegisterEthereumEscrowIntent: Register intent awaiting Eureka transfer
- NotifyEurekaPacketReceived: Update when packet arrives from Ethereum
- NotifyEurekaFinalized: Update when ZK proof verifies
- FrontSettlement: Solver fronts before finality with risk bond
- ClaimEurekaEscrow: Solver claims after finality verification
- HandleEurekaEscrowFailure: Handle timeout/failure with bond return

Design aligned with Skip Go Fast principles:
- Intent-based execution with solver fronting
- Two-stage finality (Received → Finalized) for ZK proof architecture
- Explicit risk bond mechanism
- Timeout guarantees and failure handling

15 new tests for Ethereum escrow flow (68 total escrow tests passing).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
test: add adversarial tests and testing plan for Ethereum escrow
f6a8dcc 
Add 21 adversarial tests covering economic and security attack vectors:

Economic attacks:
- Griefing (register without sending ETH)
- Front-running (double front attempt)
- Claim theft (unauthorized claim)
- Bond extraction (verify bond return on failure)
- Timeout manipulation (edge cases)

Security attacks:
- Replay protection (duplicate intents)
- Amount manipulation (less than expected)
- Fake finalization/packet notification
- Unauthorized registration/failure marking
- Wrong packet ID, sender spoofing
- Double claim, insufficient bond
- Wrong state transitions

Also adds comprehensive testing plan document covering:
- 5 test levels (unit, adversarial, integration, testnet, performance)
- Test scenarios with expected results
- Test infrastructure requirements
- Coverage goals and metrics

Total escrow tests: 89 (29 unit + 24 adversarial escrow + 15 Ethereum + 21 adversarial Ethereum)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
docs: add bidirectional escrow design for Cosmos → Ethereum flow
e81d463 
Design document for extending escrow system to support outbound transfers
where users escrow on Cosmos Hub and receive funds on Ethereum.

Key points:
- Symmetric design: same escrow + fronting + proof pattern
- Lower risk for outbound (Cosmos 6s finality vs ETH 20min)
- Proof options: Hyperlane (recommended), Eureka reverse, Optimistic
- Lower bond requirements (1.2x vs 1.5x) due to faster finality

State machine: Pending → Accepted → Filled → Released
New messages: RegisterOutboundEscrowIntent, SolverAcceptOutbound,
              NotifyOutboundFilled, ReleaseOutboundEscrow

Integrates with Skip Go Fast solver infrastructure.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@zmanian @claude
Update bidirectional escrow design with IBC-native proof mechanism
94d33cc 
Replace Hyperlane/ZK proof options with IBC Eureka fulfillment contract approach:

- Solver calls IntentFulfillment contract on Ethereum
- Contract transfers tokens to user AND sends IBC packet back to Hub
- Hub receives IBC packet as proof of fulfillment (no separate verification)
- Added Solidity IntentFulfillment contract code
- Added Rust ibc_packet_receive handler
- Simplified state machine (Pending → Filled/Expired)
- Lower bond requirement (1.2x vs 1.5x) due to reduced risk

This leverages existing IBC Eureka bidirectional infrastructure instead of
requiring additional trust assumptions (Hyperlane validators) or complex
ZK proof verification.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@zmanian