NearFusion Bridge

Project Overview A production-ready decentralized bridge connecting Ethereum and NEAR. It combines on-chain escrow contracts, off-chain automation, and messaging services to execute atomic swaps in both directions with safety guarantees. The architecture hinges on Chain Signatures–backed key management, NEAR Intents–driven workflow initiation and an enhanced-agent service that orchestrates interactions across chains.

Core Architecture Enhanced Agent (scripts/enhanced-agent.ts) Orchestrates cross-chain swaps, monitors intent events on NEAR, listens for escrow updates on Ethereum, and drives escrow lifecycle actions. It leverages Chain Signatures for secure signing and enforces hashlock/timelock logic to keep the swap atomic. EVM Resolver Suite (contracts/src/, contracts/script/) Solidity contracts deployed on Sepolia manage ETH-side escrows and include factories, resolver logic, and deployment scripts (DeployResolver.s.sol/, DeployEscrowFactory.s.sol/). They expose creation, withdrawal, and cancellation flows aligned with the HTLC semantics. NEAR Contracts (near/contracts/escrow, near/contracts/intents) Rust-based WASM contracts: Escrow contract (near/contracts/escrow/) implements the NEAR HTLC counterpart with create_dst_simple, withdraw_dst_hex, and cancel_dst. Intents contract (near/contracts/intents/) receives cross-chain intents, validates payloads, and emits structured events consumed by the agent. Chain Signatures Integration A decentralized MPC signer (NEAR_MPC_CONTRACT_ID) accessed via CS_ENDPOINT provides distributed private key control, ensuring the agent never holds raw private keys. NEAR Intents Service Users submit intents to NEAR_INTENTS_ACCOUNT_ID, which defines the desired swap direction, amounts, participant addresses, and deadlines. The enhanced agent consumes these intents to trigger cross-chain operations. Cross-Chain Workflow Intent Submission A user submits a structured intent to the NEAR intents contract (intake_intent()). The intent includes swap parameters and references to participants on both chains. Source Escrow Lock NEAR→ETH: The NEAR client script scripts/transfer-near-to-eth-correct.ts locks funds in the NEAR escrow contract (create_dst_simple) while honoring NEAR’s 24-decimal precision (memory reminder: 1 NEAR = 10^24 yoctoNEAR). ETH→NEAR: The EVM script scripts/transfer-eth-to-near.ts prepares an escrow through the resolver contract on Sepolia, handling ETH’s 18-decimal scale (1 ETH = 10^18 wei). Agent Coordination The enhanced-agent monitors new intents and escrow events on both chains. Once it detects a funded escrow on the source chain, it replicates the escrow on the destination chain, using Chain Signatures to sign transactions securely. Secret Revelation & Atomic Swap The recipient reveals a preimage on the destination chain to withdraw funds, which simultaneously publishes the secret that the origin chain uses to release funds back to the counterparty. Timelocks allow cancellation if the swap stalls.

Core Technologies & Why They Were Chosen TypeScript + tsx runner The off-chain coordination layer is written in TypeScript, letting scripts/enhanced-agent.ts share rich types between blockchain payloads, intent schemas and Chain Signatures responses while benefiting from modern tooling (pnpm, eslint, prettier). ethers v6 Used across scripts/transfer-eth-to-near.ts, deployment scripts, and the agent to talk to Sepolia RPCs, encode resolver contract calls and listen for escrow events. v6’s BigInt-first API keeps amount math precise. near-api-js 3.x Powers NEAR contract interactions for both the agent and tools like scripts/transfer-near-to-eth-correct.ts, handling account key storage, JSON-RPC queries and WASM contract method calls. Rust + cargo (NEAR contracts) Contracts in near/contracts/escrow/ and near/contracts/intents/ compile to WASM, leveraging strong typing and pattern matching for HTLC safety checks and event emission. Foundry (Solidity toolchain) contracts/script/DeployResolver.s.sol and friends use Foundry for deterministic broadcast, EVM forking and contract verification, giving repeatable deployments. 1inch partner stack @1inch/cross-chain-sdk and Chain Signatures provide partner integrations: the SDK normalizes intent payloads and quoting, while Chain Signatures (HE threshold MPC) exposes a REST-like signer so the agent never holds raw private keys.

How the Pieces Interlock Intent ingestion → agent Users call intake_intent() on near/contracts/intents/, which emits structured events. The agent subscribes via NEAR WebSocket polling, validates payloads with zod and forwards actionable jobs. Dual escrow lifecycle NEAR side uses create_dst_simple() from near/contracts/escrow/ to lock yoctoNEAR with hashlock/timelock metadata. EVM side deploys escrows through the Resolver contract compiled from contracts/src/. Events surface via ethers so the agent can mirror state. Chain Signatures signing When the agent needs to push an EVM transaction, it calls Chain Signatures’ MPC endpoint (configured in .env with NEAR_MPC_CONTRACT_ID / CS_ENDPOINT). The MPC cluster returns a partial signature that ethers assembles before broadcasting.

Notable Engineering Details & Hacks Decimal precision bridge Following the persistent memory reminder about ETH (18 decimals) vs NEAR (24 decimals), scripts/transfer-near-to-eth-correct.ts converts between yoctoNEAR and wei using BigInt guards to avoid precision loss. The agent enforces these conversions globally to prevent under/over-funding. Dry-run meta-order mode The agent can run with DRY_RUN=true (see README.md , Phase 5) to print simulated Fusion+ payloads without hitting partner APIs. This let us debug intent parsing offline before unlocking funds. Experimental prool queue prool (a lightweight task-pool) helps throttle concurrent RPC calls so the agent won’t exceed NEAR rate limits. It’s intentionally simple but effective for coordinating retries. Fallback validation If zod isn’t installed, the agent drops to lightweight schema checks to stay operational in constrained environments—handy when shipping CLI builds. Event stitching The NEAR intents contract emits high-signal logs that the agent correlates with Sepolia resolver events. A custom deduper in scripts/enhanced-agent.ts aligns block timestamps to guarantee the correct escrow pairing even under reorgs.

Partner Integrations & Benefits Chain Signatures MPC Delivers decentralized signing; the agent never stores a private key. This keeps operations non-custodial and audit-friendly. 1inch Cross-Chain SDK Supplies canonical encoding for meta-orders and quoting logic, ensuring the Fusion+ payloads generated in dry-run mode match production formats.