Ambire Wallet

Ambire is a Web3 wallet that makes self-custody easy and secure. It's the first hybrid Account abstraction wallet to support Basic (EOA) and Smart Accounts, improving security and user experience. Read more.

Environment Setup

Built in a hybrid approach (with React Native and React Native Web) so that in a single codebase we can support building cross-browser extensions, mobile apps and web apps.

This project is built with Expo's bare workflow, allowing us to extend the default Vanilla React Native with additional expo modules in the form of installable expo libraries.

More about the environment setup and prerequisites here.

Install

Install all dependencies:

yarn install

Install the ambire-common submodule, a common ground for the Ambire apps, run:

git submodule init
git submodule update

Environment Variables

Create ".env" file in the root directory and fill in all variables, see ".env-sample" for a reference.

Editor Config

Make sure your code editor has plugins that support the following configuration files: .editorconfig, .prettierrc, tsconfig.json, eslintrc.js, import-sorter.json.

Browser Extensions

Development-optimized Builds

• Start the browser extension for webkit browsers (tested mostly on Chrome and Brave):

  yarn web:webkit

  Then follow the instructions to load an unpacked extension here.

• Start the browser extension for gecko browsers (tested mostly on Firefox):

  yarn web:gecko

  Then follow the instructions to temporarily install an extension in Firefox here.

• Start the browser extension for the Safari browser:

  yarn web:safari

  Two new folders will be created:

  • build/safari-dev (dev build folder)
  • safari-extension/wallet-dev (Xcode project)

  then in the Safari browser:

  • Developer -> Developer settings...
  • Check the “Allow unsigned extensions” option. (Note: This setting may not persist after Safari is restarted.)​
  • Then the extension should be automatically added and pinned in the browser.

  NOTE: You can manage the available extensions from: Safari -> Settings... -> Extensions

  NOTE: The development script for Safari relies on the fswatch tool to automatically reload the Safari build when the development server is reloaded. If fswatch is not already installed on your system, you can install it using Homebrew with the following command:

  brew install fswatch

Production-optimized Builds

• For webkit browsers:

  yarn build:web:webkit

  And find the resulting build in the "build/webkit-prod" folder.

• For gecko browsers:

  yarn build:web:gecko

  And find the resulting build in the "build/gecko-prod" folder.

• For the Safari browser:

  yarn build:web:safari

  Two new folders will be created:

  • "build/safari-prod" (production build folder)
  • "safari-extension/wallet" (the Xcode project)

  Then, in xCode manually do (TODO: automate these steps, it turned out to be a huge challenge):

  • Delete "walletTests" and "walletUITests" targets.
  • For both targets (macOS and extension): Signing & Capabilities: Team: "Ambire Tech Ltd", Signing Certificate: Development
  • For both targets (macOS and extension): General - Identity - Version: X.X (should match the version in the app.json file, example: 4.36) and Build: X (integer, bump up on every next build submitted to the App Store Connect, example: 3)
  • For the macOS target: General - App Category: "Utilities"
  • For the extension target: General - Identity - Bundle Identifier: com.ambire.app.wallet.extension

Extract Source Maps

The production-optimized builds come with source maps files included. When preparing a production build for a browser store release, run the following commands to extract the source maps in separate directories:

• For the webkit build:

  yarn export:web:webkit:sourcemaps

  As a result, build/webkit-prod will no longer include the source map files (as before). Instead, a new folder, build/webkit-prod-source-maps, will be created to hold only the source maps. This folder should also be included in the GitHub release tag we create.

• For the gecko build:

  yarn export:web:gecko:sourcemaps

  Same as for the webkit build, but for the gecko build.

• For the Safari build: not implemented yet.

For more details, including how to trace /deminify a production reported error, see #3191.

Store-prepared Builds

Automates the steps before every extension extension store release that could be otherwise done manually:

• Makes webkit and gecko extension production builds
• Exports source maps to "clean" the builds (and to prepare for upload those source maps in the GitHub release)
• Zips the "clean" builds (stores accept zips only) and the source maps

yarn build:extensions

And find the resulting zips in the "build" folder as ambire-extension-<VERSION>-<TYPE>.zip

Mobile Apps

The Ambire v2 compatible mobile apps are yet to be developed. Coming sometime in the near future 🤞

Benzin

Ambire's transaction explorer, that makes human readable ERC-4337 transactions and contract interactions.

Comes not only as integrated module in the Ambire extension(s), but as a standalone web app also.

Development-optimized Build

yarn web:benzin

And find the resulting build in the "build/benzin-dev" folder.

Production-optimized Build

yarn build:web:benzin

And find the resulting build in the "build/benzin-prod" folder.

Ambire Legends

Ambire Legends is a gamified testing web3 app for the Ambire browser extensions. It is designed to users you discover the power of Smart Accounts via an epic onchain adventure. Read more.

Development-optimized Build

yarn web:legends

And find the resulting build in the "build/legends-dev" folder.

yarn build:web:legends

And find the resulting build in the "build/legends-prod" folder.

Others

Browser Extensions E2E Tests

Configuration

The best approach here is to follow .github/workflows/tests.yml. It contains all the necessary instructions for CI, which are also applicable locally. Make sure to:

• Set all necessary .env variables (marked as end-to-end tests configuration).
• See #1409 for more details.

Running against production

To build the webkit production version of the extension and run the E2E tests against the /webkit-prod folder, run:

yarn run test:e2e:web

Running against development

For debugging, to use the hot-reloaded webpack dev webkit build and to allow running individual tests easily run:

yarn test:e2e:web:dev

When debugging or writing a new test, it is easier to use this command, as the project is hot-reloaded with every change you make to the codebase (e.g., adding a new selector or debugging a state), eliminating the need for a complete production build (as before). Additionally, you can run tests for a single or multiple test files.

Here's how to run the tests for a single test file:

{
  "test:e2e:web:dev": "WEBPACK_BUILD_OUTPUT_PATH=webkit-dev jest --config=./tests/jest.config.js -- ./tests/basic_account/ba_transactions.test.js"
}

If you are fixing a failing CI test and want to mimic CI at 100%, you should configure the display server:

First, run Xvfb -ac :99 -screen 0 1280x1024x16 > /dev/null 2>&1 &, then set the DISPLAY variable with export DISPLAY=:99.0. By doing this, when Jest & Puppeteer are running, they will use the newly created virtual display instead of your local display. If you want to switch back to your local display, you should run export DISPLAY=:0.

See #2438 for more details.

Translations (Beta)

To scan the project for translation labels and to update translations JSON files, run:

yarn translations:scan

PS: Secondary languages not implemented / translated / fully tested yet.