Argo bridge app design brief

[kdembler]

Argo bridge app design brief

Intro

Argo bridge is an upcoming bridge between Joystream and Base L2. The goal of the bridge is to introduce JOY token on Base and allow users easy transfer of tokens between both chains using an app. Users will connect their Joystream and/or EVM wallets to transfer tokens or operate the bridge. For the time being Base will be the only external chain supported by the bridge, but we may add more chains in the future.
More context: #5084 (comment)

Actors

Bridge has 5 main actors:

1. Users - wanting to transfer their JOY tokens from one chain to another.
2. Operators - responsible for operating the bridge and facilitating the transfers.
3. Pausers - able to pause the bridge in case of emergency.
4. Viewers - wanting to see transfer details, bridge status, etc.
5. EVM Admins - responsible for governing an EVM bridge: setting/collecting fees, unpausing the bridge, etc. This role does not exist for Joystream bridge - council is responsible for governance.

Concepts

Let's break down the main concepts:

Transfer

Transfer is a user request to move JOY tokens from one chain to another. It has the following main properties:

• ID - unique identifier of the transfer. (0-0, 0-1, 31337-0, etc.)
• Status - current status of the transfer:
  • Requested - transfer has been requested by the user
  • Completed - transfer has been processed by operators and tokens have been moved
  • Reverted - transfer has been rejected by operators with explanation
• For each status, there is also a timestamp and a transaction hash where the status change happened (requested at hash, completed at time, etc.)
• Amount - amount of JOY tokens being transferred
• Source chain - chain where the tokens are coming from
• Destination chain - chain where the tokens are going to
• Source address - address of the user who requested the transfer on the source chain
• Destination address - address on the destination chain where the tokens should be sent
• Fee - fee charged by the bridge when transfer was requested. It is paid in source chain native token - transfer from Joystream will have a fee in JOY, transfer from Base a fee in ETH.

When the user requests a transfer, they burn their JOY tokens on the source chain. Later, operators process the transfer and once they agree through a multisig, they mint the same amount of JOY tokens to the destination account on the destination chain.

Bridge status/config

We may think of "bridge" as a single thing, but each source chain has its own "instance". The Joystream bridge has its own configuration and status separate from the Base bridge. Joystream bridge instance handles anything that happens on Joystream side, so requesting an outbound transfer to an external chain (burn) or completing an inbound transfer from an external chain (mint). Likewise for Base bridge instance.

Bridge instance on each chain has the following main properties:

• Status - current status of the bridge:
  • Active - bridge is operational - users can request outbound transfers and operators can complete inbound transfers
  • Paused - bridge is paused and no transfers can be requested or completed
  • "Unpausing" - bridge is waiting to be unpaused. This process takes few days.
• Fee - fee charged by the bridge when transfer is requested.
• Total fees - total amount of fees collected by the bridge
• Total burnt - total amount of JOY tokens burnt by users
• Total minted - total amount of JOY tokens minted by operators
• Operator - address of the multisig wallet able to complete transfers. Any member of this multisig is considered an operator as described in actors sections.
• Admin - address of the multisig wallet able to govern the bridge. This role does not exist for Joystream bridge - council is responsible for governance.
• Pausers - list of addresses able to pause the bridge

Timelock calls

To improve security of EVM instances of the bridge (like Base), we use timelock mechanism - all governance actions are delayed by a few days. If admin multisig wants to change who the operator (can mint tokens) is, they first need to propose the change and wait for a few days. This way, in the unlikely scenario that admin multisig is compromised, there is a window of time to cancel a malicious proposal or exit to Joystream. Each call will have a target contract (ERC20 token, bridge instance contract, etc.), function signature and arguments, for example grantRole(0x123, 0x456). Additionally, each call will have status (pending/cancelled/completed), ETA to be ready, and like transfer, timestamp and transaction hash where the status change happened.

User stories

Core user stories

These are the primary goals of the bridge app:

As a user, I want to transfer JOY tokens from one chain to another

User needs to select transfer direction (from what chain to what), provide amount of tokens and destination address. It also needs to be clear what account they're sending the transfer from, as they may have multiple connected, more on that later. We need to validate the input data. User also should see what the current fee for bridging is. We may provide an estimate of how long the transfer will take, it's probably 1-2 days. After user provides inputs, we may want to present some confirmation screen. Once confirmed, user will need to sign a transaction with their wallet to request the transfer. After it's requested, we should present user with the ID of the transfer and a link to monitor it.

We should handle cases like bridge being paused or user wallet not being connected.

In case of transferring tokens from Base, the first time a given account requests a transfer, they will first need to approve the bridge contract to spend (burn) their JOY tokens. This is a standard ERC20 approval mechanism.

As a user, I want to monitor my ongoing transfers

User should be able to see the status of their transfers, including all the relevant details.

As an operator, I want to complete a transfer

Out of scope for design for now. Operators need to be able to browse pending transfers and complete them. The process consists of multiple operators confirming a single transfer until a multisig threshold have been reached and the transfer can be completed. Let's not focus our design efforts on this for now. While a core part of the app, there will be only few operators, all DAO-internal people, so we can do something dirty for now and design this later.

As a viewer, I want to see status of the bridge

I want to see status and config of running bridge instances including most important information.

As a viewer, I want to see all bridge transfers

I want to see all transfers that have been requested, including their status and details.

Secondary user stories

As a user, I want to connect my wallets and see my JOY balances across chains

The app needs to support connecting both Joystream and Ethereum wallets at the same time. To handle EVM wallets we will use RainbowKit library which comes with pre-designed UI, which we can customize further if we want. For Joystream wallets we need to come up with something custom, but it's advisable to use similar flows as are already present in Pioneer/Atlas. User should be able to have no wallets connected, one wallet connected, or both wallets connected.
Based on their connected wallets, users should be able to see their JOY token balance on different networks.

As a user, I want to track my pending wallet transactions

Whenever user is asked for a transaction signature, we should offer them some UI to track status of that transaction - waiting for signature, waiting for confirmation, confirmed, failed, etc.

As a viewer, I want to see EVM timelock calls

Timelock calls are a crucial part of the EVM bridge security. I think it's important for regular viewers to be able to see any timelock operations at a glance. This way we can ensure that if any malicious action is ever taken, it will be noticed by the community. We probably don't need to go into too many details about those, just show status, ETA, function signature and target contract.

As a pauser, I want to pause a bridge instance on a specific chain

Pausers should be able to pause the bridge in case of emergency. This is simple - click a button and confirm a transaction, maybe with some confirmation.

As an EVM admin, I want to govern the bridge

Out of scope for design for now. We can use some dirty UI for this for now.

As a user, I want to see disclaimer information

To keep bridge operators secure, we should require all users to read and accept some disclaimer information before they can use the bridge. This could be a modal that pops up the first time a user tries to request a transfer.

As a user, I want to see FAQ

I think it would be good to provide some basic information about the bridge and how it works in a simple FAQ section.

Design

We need to come up with some design direction and color scheme for the app. I don't have any specific ideas, but let's keep it simple. For the MVP I've used a shadcn/ui component library. It comes with a lot of premade components that can be customized in a lot of ways. It could be a good idea to base our design on this library or some other to limit manual development required.

Mobile

Mobile support would be cool, but it's a bit of work, both design and implementation. To begin with we probably could require desktop browser to use the app and potentially extend support later.

MVP screenshots

Here are some screenshots from the MVP app I have currently to maybe help you visualize some of the concepts:

CleanShot.2024-06-12.at.14.10.19.mp4

[bedeho]

solid 💪

[dmtrjsg]

So from what I can infer from the brief we just need to

1. Confirm on the overarching UX structure
2. Customise the colour scheme and introduce branding
3. Focus on the users who are bridging, since all other roles are performed by tech-savvy project experts who know what they are doing in the first iteration.

Let's perhaps discuss this on a quick call @kdembler?

[msmadeline]

Hey @kdembler @dmtrjsg I've finished the first iteration of the low fidelity designs. Looking forward to your feedback

➡ Figma file: https://www.figma.com/design/QvvNbpTg1KlsSwOhZteKLH/Argo-bridge?node-id=14-413&t=FD09IUCGaAh9q4zJ-4
🎥Loom: https://www.loom.com/share/2edff7396f554719b4dcf31a47f56ace?sid=c3ef4abc-8624-43ff-8725-567829c35aa5

CC. @bedeho

[dmtrjsg]

Thank you for the great work!

Comments:

Transfer

Step 1 - input

1. In the future we will support more chains to bridge to so we need a selector in fields from and to as drop downs without the tabs. The selector will display the asset title and network. From JOY on Joystream chain to wJOY on Base chain will be the default.
2. User can with a click of a single button 🔄 to swap the from and to values.
3. The wallet balance is better to display outside of the modal.
4. We need a state of the modal which is displayed when wallet is not connected, inviting user to connect the wallet from which the transfer is made. e.g. in default view the CTA can be "Connect wallet and transfer".

Step 2 - summary

1. Estimated arrival, I would exclude as block number or date altogether.
2. JOY amount -> change to FROM, add TO" and add the Asset name (wJOY). Include amount of TO asset. As exchange rate here will be 1 to 1 but we still need to show it explicitly imo.

Step 3 - progress

1. Copy "Bridging in progress. Transaction will appear in the transfers table once processed."
2. CTA = OK. No cancellation is possible. on clicking OK modal closes.

---

Transactions table

1. My transactions <> all transactions can be a toggle control. No need to hide the two options behind additional button.
2. Need to add action: View Details, that will summon a popup with all TX metadata:

From address
From asset
Sent transaction hash:
Block number:

To address
To asset
Received transaction hash:
Block number:
Transaction fee:

3. Add a small copy icon on the address, so users know if they click they can copy the address to clipboard.

Governance

1. We need to only show pending proposals by default, if no pending proposals we just show message "no pending proposals". Pending proposals need to be displayed on top of the page as this is smth that will be viwewed more often than other info on the page.
2. We need ability to view all past proposals.
3. Since this is the admin page, perhaps subtabs (level 2 tabs) may work to split
   Bridge status
   Proposals
   Make proposal

[kdembler]

Hi @msmadeline thanks a lot!

First off, I'd like to address some points from @dmtrjsg feedback:

1. Transfer->input, I'm fine with both tabs and selector for now, but selector is indeed more future proof. Just a note, the asset will be called JOY on both chains, there won't be wJOY.
2. Transfer->summary, agreed on skipping estimated arrival, I don't think we will be able to give anything accurate here. Alternatively, we could say something like "up to 3 days" maybe, to give users some idea on how long it will take, otherwise they could expect this to be much sooner as it's the case with other bridges.

For other things:

1. I don't think we need the settings icon in the topnav.
2. Let's not include "Propose a change" in the hi-fi designs, we can do something dirty for that.
3. We may want to include some kind of "From account" selector when requesting a transfer. Reason for that is that the user is able to connect multiple accounts at the same time. We could just default to the first one by default, but it would be good to give the user an option to switch the source account from within the app.
4. What is the 3 dots icon menu at the end of transfer table row used for? I think we may want to add some transfer details view.