Monallo Documentation

An AI-powered intent recognition and DeFi interface that allows users to execute complex financial operations through natural language.

3.1 Overview and Scope

Monallo Bridge is Monallo's native cross-chain bridge using a lock-mint model: users lock native assets (ETH or PAS) on the source chain; after relayer verification, the bridge contract on the destination chain either releases native tokens to the recipient or mints wrapped assets (e.g. maoXXX.SourceChain). It is separate from MonalloIntentExecutor's intent recording and uses a dedicated MonalloBridge.sol contract for lock / release (or mint) and events.

Supported chains and tokens: Sepolia (ETH) and Polkadot Hub (PAS), both EVM. The "Polkadot Bridge" option (e.g. Snowbridge / BridgeHub) is a placeholder and not part of this specification.

3.2 Architecture Overview

End-to-end flow: the user confirms "Monallo Bridge" in the frontend; the frontend calls lock(recipient, destinationChainId) on the source chain with native value; the bridge contract locks funds and emits Locked; the relayer listens, verifies, signs, and calls release(...) or mint(...) on the destination chain; the frontend may poll a status API to show the destination tx and full receipt.

3.3 Smart Contracts

• Deployment: one MonalloBridge.sol per chain (Sepolia, Polkadot Hub), same interface.
• lock: lock(address recipient, uint256 destinationChainId), payable; increments nonce and emits Locked(sender, recipient, amount, destinationChainId, nonce).
• release / mint: only the trusted relayer triggers it; the contract verifies a signature over (recipient, amount, sourceChainId, sourceTxHash, nonce) via EIP-712 / ecrecover; then either deducts balance and transfer(recipient, amount) (release) or mints wrapped tokens to recipient (mint).
• Replay protection: the destination contract records processed releases/mints with usedNonce or (sourceChainId, sourceTxHash, nonce) so the same lock is not released or minted twice.

For a release design, the bridge contract must hold sufficient native tokens on the destination chain; on testnets this can be 1:1 or a fixed ratio (e.g. 1 ETH = 100 PAS for testing). Contract addresses and ABI are maintained in lib/bridge.ts or web3 config.

3.4 Relayer Service

The relayer: listens for Locked events on both chains; after sufficient source-chain confirmations, reads sender, recipient, amount, destinationChainId, nonce, and sourceTxHash; signs this payload with the configured relayer key and calls the destination bridge contract's release(..., signature) or mint(..., signature). Each (sourceChainId, sourceTxHash, nonce) is processed only once (optional bridge_transfers DB table for idempotency and status).

Optional API: GET /api/bridge/status?sourceChainId=...&sourceTxHash=... returns { status: "pending" | "relayed", destinationTxHash?: string } for the frontend to poll and show "Locked, waiting for cross-chain" and "Received on destination chain".

Stack aligned with Next.js (Node.js + ethers.js). Environment variables include both chains' RPC URLs, bridge contract addresses, and relayer private key; production keys should be stored securely (e.g. KMS).

3.5 Frontend and User Flow

In AI Pay's handleConfirmIntent, when pendingIntent.action === "Bridge" and the bridge type is Monallo Bridge (lock-mint): validate receiver, amount, and that source/target are limited to Sepolia and Polkadot Hub and differ; if the current chain is not the source, switch chain first; call the source-chain bridge lock(recipient, destinationChainId) with value = parseEther(amount); on success show "Locked, waiting for cross-chain…" and the source explorer link; optionally poll the status API and when relayed show the destination tx and full bridge receipt (source tx + destination tx + amount + networks + recipient).

Bridge contract addresses are configured via BRIDGE_CONTRACT_BY_CHAIN_ID or environment variables.

3.6 Risks and Considerations

• Liquidity: for a release design, the destination bridge contract must hold enough native tokens; testnets may require periodic or on-demand top-ups.
• Relayer as single point: the current design uses a trusted relayer; for trust minimization, future versions may use source-chain state proofs (e.g. block header + receipt proof); this phase uses signature + event verification.
• Polkadot Bridge: the "Polkadot Bridge" option in the UI remains a placeholder and can show "Coming soon" or be hidden.

3.7 Implementation and Extensions (Developer Reference)

• ○ Monallo Video
• ○ NFT Marketplace
• ○ DAO Governance

• ○ DeFi Aggregator
• ○ Launchpad
• ○ DEX