[Kickstart] Portales debut on Moonriver Grant Hackathon

[tnkerer]

What is Portales?

Portales is a Cross-Bridge solution for fast wrapping assets. Portales' long-term goal is to make off-chain event listeners (Oyentes) decentralized by incentivizing node maintainers with PORT tokens.

How does Portales work?

A user wants to bridge assets between two chains. By interacting with Portales Front-End DAPP, it is possible to send a request using a Crypto Wallet (i.e., Metamask) to the Portales Smart Contract requesting a cross-chain swap to initiate. Upon receiving the request from the user, a transaction is sent to the blockchain resulting in a SwapStarted event.

A listener instance called Oyente leverage Ethers.js ability to filter EVM events to monitor all SwapStarted events originating from a Portales Smart Contract and handle these as user requests for a cross-chain swap. Oyente is responsible for calling a fillSwapRequest() function on the target chain. There are four possible states for a transaction once Oyente catches a new SwapStarted event:

• Initiated: Oyente received a new SwapStarted event and just started processing it
• Error: Oyente was unable to process the request, or the target chain reverted the transaction
• Processed: Oyente has sent a transaction to the target chain, but confirmation is still pending
• Finalized: The swap transaction is confirmed on the target chain

Oyente is also responsible for populating a database with the following data:

• Oyente Event ID
• Sender Address
• Receiver Address
• Origin Chain ID
• Target Chain ID
• Tx Hash
• Tx Status
• Transfer Amount

Our authorial API will make this data available for the front-end so the end-user can follow the transaction status live on the web app.

In the Scope of the Moonriver Grant Hackathon, what is the definition of done?

• Front-End: Fully functional React App that

  • Initial port from template to a web application #27
  • Enables connecting to MetaMask; #2
  • Allow users to choose a list of available swappable ERC20 tokens; #3
  • Allow users to choose a list of available supported Networks; #4
  • Allow users to Approve the Portales Smart Contract to spend their ERC20 token balances; #5
  • Allow users to send a transaction to the blockchain to start a Swap action; #6
  • Show users in a modal element the status of the transaction along with how many steps it will take for completion; #7
  • Show users Swap history based on his account address (addresses provided by MetaMask); #8
  • Allow users to open a ticket should a transaction fail; #9
  • Allow users to open a ticket to list his ERC20 token on Portales service; #10

• Back-End: Complete infrastructure to process user swap requests on the blockchain

  • Listener (Oyente):
    • Filter events using Ethers.js; #11
    • Process data and register relevant information to database; #12
    • Send a Fill Swap Request request to target chain; #13
    • Monitor succeeded requests on target chain; #14
    • Update database with transaction status in each step; #15
  • Status Agent (Oyente Agent):
    • Estabilish a medium to provide Transaction Status from database and make it available to front-end; #16
    • If necessary, provide API endpoints for external modules to access database; #17
    • Manage authentication, in case database data contains sensitive information; #18
    • (Optional) Containerize Oyente Agent; #19

• Blockchain: Portales Smart Contracts that can

  • Register a cross-chain pair; #20
  • Emit a SwapStarted Event to inform relayers a user started a new swap; #21
  • Emit a SwapFilled Event to inform relayers a swap has been completed; #22
  • Set a Swap Fee; #23
  • Is upgradable, should a feature be implemented in the future; #24
  • Keep track to make sure duplicated requests are reverted; #25
  • Reentrancy resistant; #26

Relevant links:

Moonriver Grant Hackathon

What Are Blockchain Bridges?

Filtering EVM Events using Ethers.js