User-Stories

[MaksymZavershynskyi]

This is list of user stories. They are combined in one place as they should be solved by coherent product design vs solved one by one.

To simplify the language, the pair of contracts like TokenLocker/MintableFungibleToken will be called "connectors"

User stories:

• Developer wants to use bridge for specific ERC-20
  • Don't need to deploy anything, there are generic ERC-20 "connector" exist
    • Will be addressed by Generic Token Locker #126
  • Just include a JS library in their frontend / nodejs app to send the funds
• Developer wants to bridge NEP-21 to Ethereum
  • Don't need to deploy anything
    • Will be addressed by Generic Token Locker #126
  • Just include a JS library in their frontend / nodejs app to send the funds
• Developer wants to clone ERC-20 "connector" and customize it
  • git clone
  • edit sol & rc files
  • modify tests in this repo, that are testing end-to-end deployment + interaction of the contracts using JS library
  • run on ganache + NEAR's CI with npm run test, tests are running the relayers inside them via JS library -- don't need to run separate services
  • deploy to testnet, mainnet -- rely on existing relayers or next item
• Project / company wants to run relayer & watchdog
  • npm install rainbowup near-cli
  • use near-cli to setup everything, like accounts, instructions available in this repo
  • rainbow-bridge services up
  • rainbow-bridge services status -- outputs info on how are services doing?
  • rainbow-bridge services down -- stops services
• Developer wants to use third-party connectors
  • They can just use the same JS library to interact with any connectors
• User wants to move assets and has NEAR account
  • CLI support -- we don't really need this if we get to UI quickly
    • near bridge-send <ethereum address> my.account <token-address> <amount> -- leverages both NEAR's and existing web3 provider credentials
    • near bridge-view <token-address> my.account -- shows how much of this token on NEAR side you have
  • JS library -- this will allow us to add support on Wallet side.
• User wants to move some assets to NEAR, but doesn't have an account yet
  • Charge a bit extra on Ethereum side and relayer will create an account for the user on NEAR side (MVP - create for free if transaction has some value)
  • near bridge-create-account <ethereum address> <token-address> <amount> -- this outputs linkdrop that you can use to grab your token on NEAR side while creating an account
  • JS library for this

Important parts of the product that are missing:

• Interaction with near-cli - instead of requiring rainbow cli to reinvent all the configuration, it should leverage near-cli with NEAR_ENV and existing configurations / key management.
• sol/rs should be made into reusable packages: near-bridge, near-provider, eth-bridge, eth-prover.
• The reason for Split repo #280 is to allow npm install github repos. As far as I understand npm can't install from subfolders. If this is not true - we can ignore this.
• Separate example of single ERC-20 token locker that developer can fork that modify.
• Generic token locker / NEAR token factory that has predictable names for contracts is important
  • Especially, it's important to have an automatic way to infer account name for the token on NEAR side from ERC-20 address. It's important for UIs and other tooling. Note, that if it's not sub-account of some bridge account, this name can be squatted by someone else.
• JS library should provide an easy interface to interact with any connectors
• web3 hooks to initiate transaction for Ethereum side
• NEAR hooks to initiate transaction on NEAR side.
• A async function to wait until some transaction from one side gets finalized on the other side.
  • Some way to monitor the progress: how many confirmations for Ethereum -> NEAR, calling watchdog logic for NEAR -> Ethereum
  • Extra stuff in library (it should be there but not surfaced as main use cases): Client side relaying logic, watchdog

[ailisp]

rainbow-bridge services up

Are you suggesting to start all services in one command? we have up single individual service but no up all yet.

npm install rainbowup near-cli

rainbowup has been named as rainbow-bridge-cli as #99 . for near-cli do you mean near-shell?

@ilblackdragon

[chadoh]

start all services in one command

I think that sounds nice

for near-cli do you mean near-shell

near-shell was renamed to near-cli a couple weeks ago

[MaksymZavershynskyi]

@ilblackdragon Thank you for the highly detailed explanation! Let me summarize and propose a plan of action.

It seems like we have three themes for the user-stories:

• People should be able to hack on the bridge easily;
• Transfers should be doable through near-cli, wallet or JS app;
• Bridge services should be controllable like docker containers or pm2 services.

I propose the following timeline:

Next 3 weeks

@chadoh and me discussed this plan on a call.

• In the next 3 weeks @chadoh works on JS app that can use bridge transfers for something. This app will also be able to initialize the connectors. The hackers will use this app by forking and modifying the repo. The app will still rely on the rainbow monorepo by programmatically cloning it, like nearup does. Overall, this is a difficult task since JS code that does transfers is not trivial, and there is a lot of documentation and presentation that needs to be prepared for the hackers.

• @Kouprin is starting to work on Extract RainbowLib #297 . However, @chadoh will not count on it to be used in his example, since it might take time to implement and time to integrate into the example and write the documentation for. If it happens it is good, but we won't count on it.

• The stretch goal is to implement Generic Token Locker #126 . @Kouprin and @ailisp are working on closing the Fully Tested Bridge Release (https://app.zenhub.com/workspaces/chainmiddleware-5cea2bcf78297c385cf0ec81/reports/release?release=5ed9658f026fd74dde14faec) so they cannot help. @chadoh needs help with someone to implement Solidity contracts if we want this to happen. Can @mattlockyer help?

Until Fully Tested Bridge Release is Closed

• @Kouprin, @ailisp are working on closing the Fully Tested Bridge Release (https://app.zenhub.com/workspaces/chainmiddleware-5cea2bcf78297c385cf0ec81/reports/release?release=5ed9658f026fd74dde14faec) so they cannot help, the amount of work is larger than Mainnet Avocado Release. Additionally, @abacabadabacaba is auditing the model and the contracts.

• In parallel to this @chadoh and other people are working on usability, which includes:

  • Splitting the repo (see discussion Split repo #280). I suggest the following 3 repos: Rainbow-lib (+ rainbow-cli, rainbow-test-utils), Rainbow-sol, Rainbow-eth, Rainbow-erc20, rainbow-nep21, etc.
  • Documentation;
  • Examples;
  • There is going to be a lot of complexity with setting up the CIs.

[MaksymZavershynskyi]

Unless there are votes against it, we will proceed with this plan and this issue is going to be closed.

[chadoh]

In the next 3 weeks @chadoh works on JS app that can use bridge transfers for something. This app will also be able to initialize the connectors. The hackers will use this app by forking and modifying the repo.

One slight correction. I envision this as two apps, built in this order:

1. "Send an ERC20 to NEAR" demo app. Uses already-deployed connectors, which can be specified via URL params. Hackers can fork & modify this repo to get started.
2. "Find and Deploy Connectors" app. You can search for already-deployed TokenLocker/MintableFungibleToken pairs on Ropsten/Testnet by ERC20 address. If this token doesn't yet have deployed connectors, you can sign in with MetaMask & NEAR Wallet and pay to deploy them. This app builds .sol & .wasm files from near/rainbow-bridge during deploy and gets auto-redeployed with every commit to near/rainbow-bridge#master.

I suspect this will provide the bridge onramp needed by ~90% of hackers. The other 10% can fork near/rainbow-bridge itself.

We could create hackathon prizes for the motivated subset of that 10% who want to contribute generic ERC20→NEP21 connectors, generic or specific NEP21→ERC20 connectors, and other such things.

[ilblackdragon]

@nearmax What is the solution for using solidity contracts from external repositories without pulling them out?

[ilblackdragon]

Also please see the generic token connector here - https://github.com/near/rainbow-token-connector

I'm also trying to add more tests there, as I didn't find any tests for just connector contracts.

[MaksymZavershynskyi]

@nearmax What is the solution for using solidity contracts from external repositories without pulling them out?

You gotta pull them out. But also, you can just copy this 5 line file: https://github.com/near/rainbow-bridge/blob/master/libs-sol/nearprover/contracts/INearProver.sol

To develop MintableFungibleToken factory you would need to copy MintableFungibleToken for now.

Our testing infrastructure is very complex, and I would strongly prefer if we were not distracting ourselves with refactoring before we are actually done with major parts of testing. I don't want us to spend 1+ week extracting contracts and fixing cross-repo tests and would rather spend this time stabilizing our code. Only designing how we are going to setup testing infrastructure across multiple repos once we extract the contracts will take me or @ailisp several hours or even 1+ days.

If someone really wants to extract the contracts, then before we start extracting them, please propose a detailed plan of how we are going to setup testing infrastructure across multiple repos.

[Kouprin]

@nearmax @ilblackdragon I'm confused of what we are working on right now.
In terms of #297, I'm working on building reasonable library which can be used by our clients. The main scenarios of using are described in this topic + discussed offline with @ilblackdragon.
To make the library useful for most cases, it will contain of the following:

1. rainbow-bridge-sol contracts as a separate package;
2. rainbow-bridge-rs contracts as a separate package;
3. rainbow-bridge-lib environment and tools that includes rainbow-bridge-sol and rainbow-bridge-rs.
   According to @ilblackdragon, I expect it will cover most of the cases for our clients short-term. After the first iteration (3 weeks + hackathon), we will take feedback into account and include more user cases for middle-term goals. I expect we will extract services that using contracts to work with them independently.

Our testing infrastructure is very complex, and I would strongly prefer if we were not distracting ourselves with refactoring before we are actually done with major parts of testing. I don't want us to spend 1+ week extracting contracts and fixing cross-repo tests and would rather spend this time stabilizing our code. Only designing how we are going to setup testing infrastructure across multiple repos once we extract the contracts will take me or @ailisp several hours or even 1+ days.

I hear you as you're suggesting to stop doing (1) and (2), and go directly to extract services? Not sure if I understand you properly. Please let me know if there is any misunderstanding.

[MaksymZavershynskyi]

@Kouprin Sorry, there is miscommunication between me and @ilblackdragon , we are syncing right now.

Please continue working on:

In terms of #297, I'm working on building reasonable library which can be used by our clients. The main scenarios of using are described in this topic + discussed offline with @ilblackdragon.

I hear you as you're suggesting to stop doing (1) and (2), and go directly to extract services? Not sure if I understand you properly. Please let me know if there is any misunderstanding.

We can still have rainbow-bridge-sol and rainbow-bridge-rs as separate packages, I just suggest to keep it in the repository for now, to avoid breaking multiple tests that we have created.

[ailisp]

We can still have rainbow-bridge-sol and rainbow-bridge-rs as separate packages, I just suggest to keep it in the repository for now, to avoid breaking multiple tests that we have created.

After try work with separate rainbow-bridge-rs and rainbow-bridge-sol, i found separate repo is better to work with, because:

• rainbow-bridge-cli depends on npm package of ranbow-bridge-rs and rainbow-bridge-sol, which is a pinned version, include these repos in place cause confusion since they're included but not used
• if you want to debug and change something in rainbow-bridge-sol/rs, you can do in environment/node_modules/rainbow-bridge-sol(rs), and it immediately have effect. After done, doing same change in rainbow-bridge-sol(rs) repo and republish npm package, and bump version in ranbow-bridge-cli side

[MaksymZavershynskyi]

User stories are written. Removing it as a blocking issue from other issues.