Structure, setup, and the commands you'll use daily.
- Node.js >= 22 and pnpm 10.28+ (see
packageManagerinpackage.json) - iOS: Xcode 15+, CocoaPods via Bundler (Ruby), iOS Simulator
- Android: Android Studio + SDKs, JDK 17, emulator or device
- macOS: Watchman for fast reloads
pnpm install
pnpm run setup # Git hooks: lint/format/copyright, then tests on push
pnpm --filter mobile expo:prebuild # First run, or to regenerate native projectsMetro in one terminal:
pnpm mobile:startA platform target in another:
pnpm ios
pnpm androidBoth also work from the app folder: pnpm -C apps/mobile start|ios|android.
To regenerate native projects from scratch, pnpm -C apps/mobile expo:prebuild:clean.
Workspace packages in packages/* build to dist/. Turbo builds them before running the mobile app
or tests, so most development needs no manual build step.
Each package's build runs vite build for the JavaScript and then tsc -p tsconfig.build.json for
the declarations. That config carries the exclude list keeping test-only modules out of the
published type surface — and because tsconfig globs have no brace expansion, those patterns are
written out one per line. pnpm run check:dts-emit guards both halves.
Note
In local development Metro resolves packages directly from their src/index.ts,
so package changes show up in the app with no build.
pnpm build # every package, plus generated configuration
pnpm build:packages # workspace packages only
pnpm dev:packages # watch mode, for editors and testsRun a local Algorand node and point the app at it instead of live networks. Needs Docker running and
the AlgoKit CLI (brew install algorandfoundation/tap/algokit).
pnpm localnet # start LocalNet (algod :4001, indexer :8980, kmd :4002)
pnpm localnet:fund --new 100 # create + fund a throwaway account (prints mnemonic)
pnpm localnet:fund --new-quantum 100 # same, for a quantum account (prints seed hex)
pnpm ios # or: pnpm android
pnpm localnet:stopPoint the app at it from Settings, Developer, Node Settings: turn on Developer mode, then pick Custom network under Algorand. Selecting it opens a sheet for the algod and indexer URLs, their optional tokens, and the genesis hash and ID; Fetch from node fills the genesis values in. Save and switch applies the config at runtime, with no rebuild, no env rewrite, and MainNet and TestNet untouched.
Two things to watch:
- On a physical device,
localhostresolves to the device, not your machine. Use the host's LAN address (http://192.168.1.50:4001). pnpm localnet:resetregenerates the genesis hash, so re-enter the custom config afterwards.
pnpm localnet:quantum-checkRuns an end-to-end check of a quantum-signed transaction against LocalNet: derives a Falcon-1024 address, funds it, builds a payment with a PQ-raised fee, checks the assembled PQ envelope against algosdk's own PQ signer, then broadcasts and waits for confirmation.
The algod version pinned in tools/dev/localnet.compose.yml verifies pqsig, so on a plain
pnpm localnet the script reports PASS: confirmed in round N and the indexer serves the
transaction, with no edits to the AlgoKit sandbox. A node without pqsig reports PENDING at exit 0
once the broadcast is rejected for that reason specifically. Any other failure reports FAIL with a
non-zero exit.
The check talks to localhost:4001 directly and needs no app config. LocalNet runs in dev mode, so
last-round stays at 0 until a transaction is submitted; that is not a stalled node.
If the indexer sits at round 0 after a transaction (curl -s localhost:8980/health,
pnpm localnet:logs), suspect a stale cached image: docker pull
algorandfoundation/conduit-localnet:latest and algorand/indexer:latest, then
pnpm localnet:reset.
pnpm test:conformance runs the app's builders, keystore, signing and error-handling code against
this LocalNet instead of a mock. conformance/README.md covers what it
proves, its prerequisites and its known gaps.
pnpm evmnet # seven Anvil nodes, one per EVM chain on its testnet chain id (ports 8545-8551)
pnpm evmnet:status
pnpm evmnet:reset # recreate every node from a fresh chain
pnpm evmnet:stopDocker is the only prerequisite; the Foundry image is pinned by digest in
tools/dev/evmnet.compose.yml.
pnpm test:conformance:evm runs the app's EVM derivation, signing, transfer, fee, submission and
error-handling code against these nodes, with Foundry's cast as the independent oracle.
conformance-evm/README.md covers what it proves and its known gaps.
pera-react-native/
├── apps/
│ ├── mobile/ # React Native app (UI layer)
│ └── browser/ # Chrome MV3 browser extension
├── packages/ # Headless business logic (one per domain)
│ ├── accounts/ # Account management and state
│ ├── assets/ # Asset management
│ ├── browser-runtime/ # Browser extension runtime (message routing, dApp/WC plumbing)
│ ├── chain-algorand/ # Algorand chain: node/indexer access and per-package adapters
│ ├── chain-ethereum/ # Ethereum chain: descriptor, module and its adapters (viem)
│ ├── config/ # Configuration and environment
│ ├── database/ # Local persistence
│ ├── devtools/ # Development tools
│ │ └── tsconfig/ # Shared TypeScript configuration
│ ├── kms/ # Key Management System integration
│ ├── shared/ # Common utilities, types, and models
│ ├── signing/ # Signing pipeline
│ ├── walletconnect/ # WalletConnect integration
│ └── … # contacts, swaps, staking, card, names, …
├── extensions/ # Platform adapters behind one interface
│ ├── platform/ # The platform contract
│ ├── platform-react-native/ # React Native implementation
│ ├── platform-chrome/ # Chrome implementation
│ ├── provider/ # `getProvider()` accessor used by packages
│ └── … # ledger-*, vault-chrome, passkey-autofill
├── conformance/ # LocalNet conformance suite
├── conformance-evm/ # EVM conformance suite (Anvil)
├── tools/ # Development and CI scripts
├── specs/ # OpenAPI specifications
└── docs/ # Project documentation
extensions/ means platform drivers, not browser extensions. See
Architecture for why the two names collide.
The workspace definition is in pnpm-workspace.yaml.
- Task runner and cache: Turborepo (scripts in
package.json) - Formatting: oxfmt
- Linting: Oxlint via
.oxlintrc.json - Dead code, cycles, duplication: fallow via
.fallowrc.jsonc - TypeScript project references via
packages/devtools/tsconfig
pnpm build # build all packages
pnpm build:packages # build only workspace packages
pnpm dev:packages # watch mode for package development
pnpm test # run all tests (unit + integration)
pnpm test:unit # run unit tests only
pnpm test:coverage # run tests with coverage
pnpm lint # report lint/type-aware issues
pnpm lint:fix # auto-fix lint issues and licence headers
pnpm lint:docs # report stale references in Markdown, shell and YAML
pnpm format # format files
pnpm fallow # report unused code, circular deps, duplicationfallow finds cross-module unused exports, files, types and
dependencies, plus circular dependencies and code duplication, which neither Oxlint nor tsc cover.
Config lives in .fallowrc.jsonc.
It runs in CI as the Dead Code job in ci-pre-merge.yml:
findings appear in the job summary, and any rule set to "error" (unused files, exports and
dependencies, cycles) fails the PR. A dependency used outside the import graph (an autolinked native
module, a config plugin, a Metro polyfill) goes in ignoreDependencies with its reason. Do removals
in reviewed PRs, not via fallow fix.
| Doc | Covers |
|---|---|
| Architecture | Layering, platform drivers, per-platform features |
| Style Guide | Decisions behind the enforced rules |
| Testing | Unit, integration harness, locale tour |
| Chains | Chain model, build and kill-switch knobs, adding a chain |
| Security | Reporting a flaw, key custody, vault limits, supply chain |
| Offline & Paused State | DB-first reads, the paused render contract |
| Translation Guide | Locale bundles, plural traps, per-language rules |
| WebView Architecture | The in-app webview bridge, its trust model and v3 method set |
| Pera Card | Baanx contract, onboarding, AutoDraw |
| CI Automation | Jira sync and release publishing |
| Release | Tags, pipelines, store submission |
| Documentation Standards | Where a given piece of documentation belongs |
| Contributing | Branches, commits, PRs |
For app-specific notes, see apps/mobile/README.md.