See BeamFi Pitch Deck for its vision.
See BeamFi Payment Protocol in Supernova Hackathorn 2022. Top 7 submissions in DeFi.
The following Quick Start guide is created from the perspective of Beam App.
We have a new Web Frontend - BeamFi App developer guide created from the perspective of BeamFi Protocol.
Switch to dev Git branch if you haven't.
- Install NodeJS 16.19 or if you have NVM:
nvm use
- VSCode
Install Extensions: ESLint, Prettier
The default configuration is set to use BeamFi dev canisters for ease of frontend development so that it doesn't require local IC replicas.
> npm install
> npm run dev
You will need Plug Wallet chrome extension https://plugwallet.ooo/ to create Beam in "Beam Out" and some ICP tokens. You can get ICP tokens from exchanges like Binance AU or speak to Henry ([email protected]) to get some ICP for your testing. (Note they are real ICP with true value so your testing is as close to the real world as possible).
dev - all development code will first merge to dev first, any push to dev will trigger deployment to https://dev.beamfi.app
main - this is where the production stable code is, it requires a manual trigger in Github Action to deploy to https://beamfi.app
- When working on a new feature, create a new feature branch based on main branch and work on there.
- When it is ready for testing or review, submit a Pull Request to dev branch.
- The main contributor will review and give feedback.
- When the review is complete, the PR will be merged to dev for testers to try it in frontend
- When it passed the manual human tests, new changes will be merged to main branch and the manager can trigger Github Action to deploy to production.
pages - Main page entry
ui/components - React Components
ui/declarations - IC Candid (similar to Solidity ABI) files for interacting with Canisters (generated from DFX cmd)
ui/service/actor - Service locator pattern to make actor for interacting with canisters
ui/components/auth - Plug Wallet chrome extension interaction code (similar to Metamask). More details https://docs.plugwallet.ooo/
ui/styles/theme.js - Chakra themes style
scripts - CI / CD scripts for use with Github Actions
Frontend UI is a SPA (Singel Page Application) developed with NextJS, React and Chakra UI. Since the webapp is intended to run as static page deployed to IC assets canisters, only the client-side features of NextJS are used. All server-side features like dynamic routing or server-side rendering will not work.
React Router is used for client-side routing. See /pages/index.js and /ui/components/beam/screen
The magical part that connects canister ID to frontend app is dfx.webpack.config.js. It reads canister_ids.json and exports it as NEXT_PUBLIC_BEAM_CANISTER_ID for Beam canister for example. See /ui/declaration/beam/index.js
When changes are made to BeamFi protocol canisters, it is important to copy the candid files to Beamapp so that frontend app can see the new functions and data structures.
E.g BeamOut has new changes
Generate new declaration files then copy to Beamapp.
> cd ${BeamFi protocol home}
> dfx generate beamout
> cp src/declarations/beamout/* ${Beam app home}/ui/declarations/beamout
Open index.js to delete:
createActor(canisterId)
since it has conflicts with NextJS server-side rendering
Notes: You can delete unused files like *.wasm
Two GitHub workflows are used for deploying to dev (https://dev.beamfi.app) and prod (https://beamfi.app)
The main difference between them is the canister ids they connect to but all of the canisters run on IC mainnet canisters. There is no IC testnet. Treat the dev environment like a staging environment. Your local IC replicas is your testnet.
When you have BeamFi canister setup in local IC replicas, you can connect to it by:
- From BeamFi Protocol Git project, copy canisters_id.json to .dfx/local/canisters_id.json
- copy env.iclocal to env.development and env.production (note env.production is only required if you run next export)
- run NextJS server
> cp env.iclocal env.development
> npm run dev
You don't want to do this most of the time but in case you need to debug production issues.
Copy canisters_id_prod.json to canisters_id.json and start NextJS server
> cp canisters_id_prod.json canisters_ids.json
> cp env.ic env.development
> npm run dev
At the moment, BeamFi frontend app is hosted in Firebase Hosting as static pages export for best performance through CDN.
We intend to provide an alternative option with better security by deploying it to IC assets canisters with custom domain (using ICFront) so that we can use HTTP Assets Certification for users who need the best security. https://wiki.internetcomputer.org/wiki/HTTP_asset_certification https://github.com/dfinity/icfront
Henry Chan, [email protected] Twitter: @kinwo
Please feel free to raise issues or submit a pull request.
See the License file for license rights and limitations (MIT).