Pelagus is a community owned and operated Web3 wallet, built as a browser extension.
Try this.
$ nvm use
$ nvm install
$ npm install -g yarn # if you don't have yarn globally installed
$ yarn install # install all dependencies; rerun with --ignore-scripts if
# scrypt node-gyp failures prevent the install from completing
$ yarn start # start a continuous webpack build that will auto-update with changesOnce the build is running, you can install the extension in your browser of choice:
- Firefox instructions
- Chrome, Brave, Edge, and Opera instructions
- Note that these instructions are for Chrome, but substituting
brave://extensionsoredge://extensionsoropera://extensionsforchrome://extensionsdepending on browser should get you to the same buttons.
- Note that these instructions are for Chrome, but substituting
Extension bundles for each browser are in dist/<browser>.
By default, the yarn start command rebuilds the extension for each browser on
save. You can target a particular browser by specifying it in the command, e.g.
to only rebuild the Firefox extension on change:
# On change, rebuild the firefox extension but not others.
$ yarn start --config-name firefox
# On change, rebuild the firefox and brave extensions but not others.
$ yarn start --config-name firefox --config-name braveIn some Linux distributions such as Ubuntu 20.04, you need to explicitly
tell npm where your python3 executable is located before running the above
commands successfully:
$ npm config set python /usr/bin/python3The extension is built as two packages, background and ui. background
contains the bulk of the extension's background script,
while ui contains the code powering extension popups.
These are separate packages in order to emphasize the difference in attack
surface and clearly separate the threat models of each. In particular, ui
is considered untrusted code, while background is considered trusted code.
Only background should interact with key material regularly, while ui should
only interact with key material via a carefully maintained API.
The background package is also intended to minimize external dependencies
where possible, reducing the surface exposed to a supply chain attack.
Dependencies are generally version-pinned, and yarn is used to ensure the
integrity of builds.
Builds are designed to be run from the top level of the repository.
If you’re on macOS, install Homebrew and run scripts/macos-setup.sh. Note
that if you don’t have Homebrew or you’re not on macOS, the below information
details what you’ll need. The script additionally sets up pre-commit hooks.
$ ./scripts/macos-setup.sh
If you need to create or update a validation function then:
- You need to write the schema in the
.tsfile to have correct typing. - Add the new schema with the validator function name to the
generate-validators.tsfile - You need to update the
jtd-validators.d.tsorjson-validators.d.tsfiles with the typing definition - run
yarn run generate:validators - import it in your code and happy validating :)
This setup is necessary so we don't need to include unsafe-eval in the CSP policy.
If you can't use the macOS setup script, here is the software you'll need to install:
jq: Instructionsnvm: Instructionspre-commit: Instructions
Before committing code to this repository or a fork/branch that you intend to
submit for inclusion, please make sure you've installed the pre-commit hooks
by running pre-commit install. The macOS setup script does this for you.
For more detailed description see ./dev-utils/local-chain/README.md
Quick Start:
$ cd dev-utils/local-chain
$ yarn install
$ yarn start
Commits on the Pelagus repository are all required to be signed. No PR will be merged if it has unsigned commits. See the GitHub documentation on commit signing to get it set up.
This repository uses yarn version to create new versions. Typical usage:
$ yarn version --patch # bump patch version, e.g. 0.0.5->0.0.6
$ yarn version --minor # bump minor version, e.g. 0.1.5->0.2.0Major releases generally require more discussion than this automation allows, but can be managed the same way.
Bumping a version in this way will do a few things:
- Ensure the commit is running on the correct branch (
release-<new-version>) for review. If you are on a different branch, the script attempts to switch to a new branch based on the latest origin/main. Releases should generally only add version bumps to the main branch. - Synchronize the extension manifest version to the updated package version.
- Commit, tag, and push the new version and branch.
Once the branch is pushed, you should open a pull request. This will do any further processing, including potentially managing automated submission of the new version to extension directories (as relevant).
$ yarn build # create a production build of the extensionThe build script will generate a ZIP file for each browser bundle under the
dist/ directory.
$ yarn lint # lint all sources in all projects
$ yarn lint-fix # auto-fix any auto-fixable lint issues
$ yarn test # run all tests in all projects
Because lint configurations can occasionally evolve in a way that hits many
files in the repository at once and obscures the functional blame readout for
files, this repository has a .git-blame-ignore-revs file. This file can be
used to run git blame while skipping over the revisions it lists, as
described in the Pro Git book
reference
and this Moxio blog
post.
To make use of this, you can do one of the following:
- Run
git config --global blame.ignoreRevsFile .git-blame-ignore-revsto configure git to globally look for such a file. The filename is relatively standard across projects, so this should save time for other projects that use a similar setup. - Run
git config blame.ignoreRevsFile .git-blame-ignore-revsto configure your local checkout to always ignore these files. - Add
--ignore-revs-file .git-blame-ignore-revsto yourgit blameinvocation to ignore the file one time.
The GitHub UI does not yet ignore these commits, though there is a community thread requesting the feature. In the meantime, the GitHub blame UI does allow you to zoom to the previous round of changes on a given line, which relieves much of the annoyance; see the GitHub blame docs for more.
Here is a light architecture diagram describing the relationship between services (in the API package) and the interface and browser notifications:
┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ ____ _ │
│ / ___| ___ _ ____ _(_) ___ ___ ___ │
│ \___ \ / _ \ '__\ \ / / |/ __/ _ \/ __| ┌────────────────────┼──┐
│ ___) | __/ | \ V /| | (_| __/\__ \ │ │ │
│ |____/ \___|_| \_/ |_|\___\___||___/ │ │ │ ┌─────────────────┐
│ Chain │ │ │External Services│
│ - Blocks ━━━━━━━━━━━━┓ │ │ │ │
│ ┌────subscribe (incoming or outgoing tx status)───▶ - Transactions ┃ │ │ │ Local node │
│ │ ┃ │ │ │ │
│ │ ┃ │ │ │ Alchemy │
│ │ ┃ │ ├───▶ │
│ │ Indexing ┃ │ │ │ BlockNative │
│ │ - Accounts ┃ │ │ │ │
│ │ - ERC-20 balances ━━━━╋─────┼──┘ │ CoinGecko │
│ ├───subscribe (eg balance changes), get balances───▶ - ERC-721 ownership ┃ │ │ │
│ │ - Governance proposals ┃ │ │ │
│ │ - On-chain prices ┃ │ └─────────────────┘
│ │ ┃ │
│ │ ┃ │ ┌────────────────┐
│ │ Keyring ┃ │ │ │
│ ├──────list accounts, sign tx, sign message───────▶ - Native ────────────────╋─────┼──────▶ Extension │
│ │ - Remote ┃ │ │ Storage API │
│ ┌──────────┴──────────┐ ┃ │ │ │
│ │ │ ┃ │ └────────────────┘
│ │ │ ┃ │
│ │ Wallet API │──────┐ Preferences ━━━━━━━━━━━━━┫ │
│ │ │ │ ┃ │ ┌────────────────┐
│ │ │ │ ┃ │ │ │
│ └──────────▲──────────┘ │ Notifications ┃ │ │ │
│ │ │ - Ephemeral ┣━━━━━╋━━━━━━▶ IndexedDB │
│ │ └──────pull and subscribe───────▶ - Application ━━━━━━━┛ │ │ │
│ │ - Security-critical │ │ │
│ subscribe │ │ └────────────────┘
│ and get │ │
│ │ │ │
│ │ push │
│ │ │ │
└─────────────────▼──────────────────────────────────────────────────────────────┼────────────────────┘
┌──────────────────────────────────┐ ┌───────────────▼───────────────┐
│ │ │ │
│ │ │ │
│ Wallet interface │ │ Browser notifications │
│ │ │ │
│ │ │ │
└──────────────────────────────────┘ └───────────────────────────────┘
┌───────────────┐
│ │
│ Internal dApp │
│ │
└───────────────┘
┌──────┐ ┌──────┐
│ Earn │ │ Swap │
└──────┘ └──────┘
Extension content lives directly under the root directory alongside
project-level configuration and utilities, including GitHub-specific
functionality in .github. Extension content should be minimal, and
largely simply glue together UI and wallet code. Manifest information
is managed in the manifest/ subdirectory as described below.
Here is a light guide to the directory structure:
.github/ # GitHub-specific tooling
package.json # private extension package
webpack.config.js # Webpack build for extension
src/ # extension source files
background.js # entry file for the background extension script; should be
# minimal and call in to @pelagus/pelagus-wallet
ui.js # entry file for the frontend UI; should be minimal and bind
# the functionality in @pelagus/pelagus-ui
dist/ # output directory for builds
brave/ # browser-specific
chrome/ # build
edge/ # directories
firefox/
brave.zip # browser-specific
chrome.zip # production
edge.zip # bundles
firefox.zip
build-utils/ # build-related helpers, used in webpack.config.js
*.js
dev-utils/ # dev-mode helpers for the extension
extension-reload.js # LiveReload support for the extension.
manifest/ # extension manifest data
manifest.json # common manifest data for all browsers
manifest.chrome.json # manifest adjustments for Chrome
manifest.dev.json # manifest adjustments for dev environment
manifest.firefox.dev.json # manifest adjustments for Firefox in dev
background/ # @pelagus/pelagus-background package with trusted wallet core
package.json
ui/ # @pelagus/pelagus-ui package
package.json
Firefox requires to upload source code if minifier is used and to be able to compile identical output to the uploaded package. Our builds are environment dependent at the moment because of the minification and source map process. Long term solution will be to upgrade our build process to be able to produce identical file assets, but until then we use Docker.
- install and setup docker: https://docs.docker.com/get-docker/
- git clone [email protected]:tallycash/extension.git tallyho-firefox
- cd tallyho-firefox
- git checkout tags/latest_release-tag
- .env.prod: fill in the prod API keys
./firefox-build.sh- mv firefox.zip ../
- git clean -fdx
- rm -rf .git
- cd ..
- zip -r tallyho-firefox.zip tallyho-firefox
Pelagus currently only supports English as the default language. We distill english strings to _locales to prepare for localization.
For other languages, we will use language code defined in Support locales. We will use weblate for crowd translation, and will commit back to the github periodically after these translations are QA'ed.
The GitHub Actions workflow is defined in .github/workflows/ and is responsible for building, testing, and pushing a release for the extension to GitHub. It triggers when a new commit is pushed to the main branch with a tag that matches the pattern v*.
In order to create a new release, you need to create a new tag and push it to the repository. The tag should be in the format v*, where * is the version number. For example, to create a new release with version v1.0.0, you would run the following commands:
$ git tag v1.0.0
$ git push origin v1.0.0You can also manually run the build workflow by going to the Actions tab in the GitHub repository and selecting the Build-Manual workflow.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent