FlowJP Community Proposal: Product Requirements Document including Technical Overview

[0xys]

Overview

The Batch Token Transfer Tool allows for a user to easily set up and automate transfers to multiple Flow wallet addresses from a single Flow wallet address. Useful to anyone who manages a community or works with multiple collaborators, this tool saves users the time required to initiate transfers individually to large groups of people.

Team

• Ara: Flow JP Community Lead | GitHub Twitter
• 0xys: Crypto engineer | GitHub

Architecture and Technology

• Frontend: Next.js, TypeScript
• Transaction Code: Cadence
• Test: Cadence tester with Go
• Hosting: modern Host service like Vercel with automatic and seamless CI/CD

User Experience

1. Let’s start with our dapps home screen.
2. At the center of the page is the button with which the users can connect to a third-party Flow wallet (Blocto) to our Dapps.
3. Once any third-party wallet is connected to our dapps, the list of tokens and its balance held by the user's wallet is displayed at the center. By default, FLOW token is selected but users may select other tokens.
4. Below the list is the expandable textbox, in which the list of recipients’ addresses and the amount is inputted in a certain format as a batch. The format validation may be implemented.
5. Also, the validation runs to make sure the sum of the sent amount is lower than the user’s balance.
6. If all validations passed, initially-gray Send button is now activated.
7. Clicking Send button will open a dialog displaying the summary of the batch transfer and Approve button beneath. If approved, a connected third-party wallet is opened and a transaction is ready to be authorized and broadcasted.
8. Listening to the chain event to see the status of the sent transaction. Once broadcasted, the user gets notified and the link to Flowscan may be displayed.
9. During chain spork and any kinds of outage, the user gets notified that the service is unavailable.

Maintainance Plan

• Frontend
  • Implementation to enhance maintainability so that:
    • Any new third-party wallet can be easily integrated.
    • Token type agnostic
      • Adding and blacklisting Fungible Token may be easy.
    • Minimum and modular design to ensure future extensibility
  • Use of TypeScript
• Cadence
  • Thorough test cases to be covered to assess the validity of the logic in case of breaking change in Cadence.
    Hosting Service
  • The code changes made to the main branch should trigger CI/CD process and the web page is updated.

Past Project

We have already created the batch transfer tool to distribute bounties to the event participants.

• link: https://flow-challenge-nft.web.app/batchSend
• source: https://github.com/flow-japan/flow-challenge-nft

Misc

This document is also shared in google doc: https://docs.google.com/document/d/1ZZgFD7otoFZkJv_xrvpaz4g2JMsT130NXCw-l2PRM5g/edit?usp=sharing

[avcdsld]

I have been a Cadence code developer since the beginning and have developed various tools for the Flow Dev Community. I believe that we can develop a better tool that satisfies the desired requirements.

[zikewu]

Hey @avcdsld and @0xys thanks for submitting the PRD. Your previous batch transfer tool looks awesome! Dapper Collectives' engineering team will review your PRD and get back to you in the next 1-2 weeks.

[markedconfidential]

Hello @avcdsld and @0xys! Thank you for your patience while we reviewed your proposal for the Batch Transfer Tool.

After careful review, the Dapper Collectives team has decided that your proposal for this bounty is compelling and we'd like to request a couple of refinements to the proposal in order to evaluate moving forward:

Front-End Engineering Support

According to your proposal, there is a single developer working on the bounty with you. They're listed as a 'crypto engineer', can you clarify whether or not they are able to also handle front-end engineering work that the project requires? Alternatively, you may choose to bring on a front-end engineer to support you.

UI Design Support from Dapper Collectives

In the spirit of collaborating with our bounty partners, we'd like to offer input on the user interface design and user experience for the the Batch Transfer Tool in order to ensure it is as accessible and easy-to-use as possible. Please confirm that this is acceptable to your team— we can decide at a later date if this input should take the form of a brief call, asynchronous notes on UI designs, or some other format.

---

Feel free to ask any clarifying questions about this feedback! We look forward to your response. Pending review of your response to the feedback, we will wrap up any further questions and aim to approve awarding the bounty to your team.

[0xys]

Thank you for giving us the feedback!
Happy to hear that our proposal has been accepted and we can contribute to further development of Flow ecosystem.

Frontend dev

Maybe our job titles are misleading. @avcdsld is an experienced developer in frontend, particularly Next.js. And I (@0xys) also have a fair experience of frontend. So, we can manage the frontend development on our own with @avcdsld taking a lead.

UI Design

Definitely welcome more people engaging in brushing up UI designs, which is core to our project.

Thank you again and hope to work with you all.

[markedconfidential]

@0xys @avcdsld Thank you for your thoughtful responses! On behalf of the Dapper Collectives team, I'm excited to announce that we'd like to award this bounty to the FlowJP team!

With the initial milestone complete, @zikewu will be reaching out with details on next steps soon. Looking forward to collaborating together with you!

[zikewu]

Congrats again @0xys @avcdsld !!! Can you guys give me your email contact so I can send over the payment details?

[0xys]

These are our emails addresses. Please, have a look.

• @0xys : 0xys1@proton.me
• @avcdsld : arandoros@gmail.com

[avcdsld]

Milestone 2: Front-End Prototype

@markedconfidential @zikewu It's been a little while, but we have created a front-end prototype. It is now working on testnet.

Demo site: https://batch-token-transfer-tool.vercel.app/

We are still implementing some features such as validation, csv upload and custom token. But the rough front design is complete.
We would appreciate your feedback. If you have a logo, UI design, etc. that you prefer, we can change it.

[deayora]

@avcdsld upon first click - it's looking amazing! the team and I are going to review this tomorrow and get back notes hopefully by end of week. Awesome work :)

[markedconfidential]

@avcdsld Hello hello! We've reviewed the prototype and are very happy to report that we can consider the 2nd milestone complete!

From our initial check, all of the basic product requirements are in order.

Please note that we will likely contribute updates to the front-end design before the launch of this tool, but we are not expecting your team to handle that specific work as it is out of scope for the bounty.

Next steps:

• Please move forward with the work required to get the tool ready for the 3rd milestone. As a reminder, by that point the batch transfer tool should be in a production-ready state for a full code review/audit.

@zikewu Please coordinate with the team on details regarding payment for the 2nd milestone!

[0xys]

On the verge of Phase 3

Hi, @markedconfidential @zikewu
Thanks and happy to hear we're moving to 3rd phase!

As we get closer to fixing the product design, I want to share one concern over how to handle custom fungible token.

Unlike Ethereum, Flow users can't just send custom token to any accounts. To send token, the receivers must have allocated in their account storage a specific "receiver module" to each receiving token type. This "receiver module" is called "vault" in Flow term. Flow token doesn't need this vault since it's native token. But, any types of user-defined fungible token require this vault module to be present in the accounts interacting with the token. Remember each type of token requires its own type of vault, so n vaults are needed if you want to have n different tokens in your account.
For this Flow-specific technical reason comes the unique ceremony when people use custom token: They create a vault before receiving new token.

Finally, speaking of our batch transfer tool, how should we handle token transfers that destined to accounts who don't own the vaults for that token? We came up with the following possible solutions:

1. Just let the transaction fail
2. Pre-Validate and notify such receivers. And ask users to remove such receivers.
3. For vault-less receivers, we send token to "temporary contract," from which receivers will later claim their tokens after they setup their vault. "temporary contract" is like a registry, in which claimer address and claimable token amount are recorded. It holds unclaimed token in the contract until it's claimed by registered claimer. For this scenario, we need a separate page for claimer. So, frontend will need to be changed a bit. And, someone must maintain admin key of the contract in secure and trusted manner (he can steal unclaimed fund).

I want to hear from you which one of solutions is the closest to the ideal final product?

[markedconfidential]

@0xys Hello! We are doing some research to determine what the best plan of action is for this challenge; thank you for highlighting it. Hoping to get back to you this week with a clear direction to move forward in.

[markedconfidential]

@0xys Hello! After discussing with the Dapper team, we've ascertained that the recommended best practice is to avoid the temporary contract approach and instead assume that Senders are going to be alerting Recipients that they need to instantiate the receiver module in their account before receiving funds.

In most scenarios, such as a DAO, this is likely to be a simple message to members of the group. So, for this MVP of a Batch Token Transfer tool, we're comfortable moving forward with the assumption that we're going to allow transactions to fail if the Sender tries to send tokens to an address that hasn't instantiated a receiver module.

In the future, we'll explore ways to make it easier for Receivers to instantiate vaults for common/popular/vetted tokens.