Wallet EVM Bermuda Usage

Install the module, create its two account types, and read a shielded address or balance. This setup does not submit a transaction. To move testnet funds, follow Shield, Transfer, and Withdraw.

Prerequisites

Use Node.js 22 and npm 10 for the examples below, with a Plasma testnet RPC endpoint that reports chain ID 9746. Node 22 is the example runtime and the module's development/test toolchain floor; it is not a verified minimum for every library consumer.

Your application supplies a BIP-39 mnemonic or Uint8Array seed from its secret storage. Keep it out of source code, logs, analytics, and error reports. These examples use seed-backed derivation rather than a hardware or custom signer.

Creating the shielded account reads the chain from the wallet provider. Balance queries and operations also need the SDK's configured services. A custom wallet RPC does not redirect the SDK's own RPC, relayer, chain-state, policy/compliance, or proof-artifact endpoints.

Install

The package is not on the npm registry. Install this exact GitHub revision, plus the WDK peer versions used by these examples. ethers supplies the operations guide's public RPC and contract checks.

With npm 10:

npm install --save-exact \
  'git+https://github.com/BermudaBay/wdk-wallet-evm-bermuda.git#6476ea5f79d669968b0d0fd0a1413b962f61129f' \
  @tetherto/wdk-wallet@1.0.0-beta.17 \
  @tetherto/wdk-wallet-evm@1.0.0-beta.17 \
  ethers@6.17.0

The source manifest declares version 0.1.8; that is not an npm release. Import the installed package as @bermuda/wdk-wallet-evm-bermuda, regardless of its GitHub repository name.

The module declares both WDK peers in the range >=1.0.0-beta.17 <2.0.0. The commands save exact 1.0.0-beta.17 versions for these examples. Retain your generated lockfile so subsequent installs reuse the same dependency graph. A declared peer range does not establish that every version in it has identical behavior.

npm 12 and Later

The upstream installation instructions require admission flags for the Git dependency and its transitive HTTPS SDK dependency:

npm install --save-exact \
  'git+https://github.com/BermudaBay/wdk-wallet-evm-bermuda.git#6476ea5f79d669968b0d0fd0a1413b962f61129f' \
  @tetherto/wdk-wallet@1.0.0-beta.17 \
  @tetherto/wdk-wallet-evm@1.0.0-beta.17 \
  ethers@6.17.0 \
  --allow-git=root --allow-remote=all

--allow-git=root admits Git dependencies declared by your project. --allow-remote=all admits remote dependencies throughout the installation, including the Bermuda SDK declared by this package. These flags control dependency admission; they do not verify the dependencies' code or services.

Create the Accounts

Save this factory as wallet.mjs. The application passes its seed and a verified Plasma testnet RPC URL:

import WalletManagerBermuda from '@bermuda/wdk-wallet-evm-bermuda'

export async function createBermudaSession(seed, rpcUrl) {
  if (!rpcUrl) throw new Error('A Plasma testnet RPC URL is required')

  const wallet = new WalletManagerBermuda(seed, {
    provider: rpcUrl
  })

  try {
    const ethereumAccount = await wallet.getAccount(0)
    const bermudaAccount = await wallet.getBermudaAccount(0, 0)

    return { wallet, ethereumAccount, bermudaAccount }
  } catch (error) {
    wallet.dispose()
    throw error
  }
}

ethereumAccount is an ordinary public EVM account. bermudaAccount is a separate shielded account derived from the EVM account's private key. The first getBermudaAccount() argument selects the EVM account at relative path 0'/0/index; the second selects a Bermuda subaccount. Both default to 0 and must be non-negative integers.

Unlike the EVM account's asynchronous address getter, bermudaAccount.getAddress() returns its address synchronously. It is a Bermuda address, not an EVM recipient address.

For another shielded subaccount under the same EVM account:

const anotherBermudaAccount = await wallet.getBermudaAccount(0, 1)
const recipient = anotherBermudaAccount.getAddress()

Repeated calls with the same indices reuse the same live account. See API Reference for disposal and error behavior.

Read a Shielded Balance

Save this reader as read-balance.mjs. The caller supplies the verified token address for Plasma testnet:

import { createBermudaSession } from './wallet.mjs'

export async function readShieldedBalance(seed, rpcUrl, tokenAddress) {
  const session = await createBermudaSession(seed, rpcUrl)

  try {
    const publicAddress = await session.ethereumAccount.getAddress()
    const shieldedAddress = session.bermudaAccount.getAddress()
    const balance = await session.bermudaAccount.getTokenBalance(tokenAddress)

    return { publicAddress, shieldedAddress, balance }
  } finally {
    session.wallet.dispose()
  }
}

The balance is a bigint in the token's base units. The testnet operations guide supplies the scoped USD₮0 address and verifies its six decimals. Use bigint base-unit amounts in fund-moving calls.

To read several tokens in an existing session, call getTokenBalances(tokenAddresses). Its result is a record keyed by lowercase token addresses, with bigint balances. An absent token UTXO set totals 0n.

Runtime Requirements

The Bermuda SDK generates proofs and accesses its configured services. Supply outbound network access and writable storage for the prover's common reference string (CRS), its setup data. First use downloads about 38 MB and stores about 105 MB unpacked in ~/.bb-crs, or the directory configured by CRS_PATH.

The wallet RPC and the SDK's configured provider must refer to the intended Plasma testnet deployment. An account derivation or successful import does not establish that balance scanning, proof generation, or relay submission is available.

Bare

Bare selects the package's conditional bare entrypoint. It loads bare-node-runtime, supplies the SDK prover's missing stream/worker interfaces, and patches TextDecoder and WebAssembly compilation/instantiation globals for the process.

Import @bermuda/wdk-wallet-evm-bermuda before anything that loads @bermuda/sdk or @aztec/bb.js, so those dependencies receive the package's import mappings. Under Bare, the prover uses a single-thread WebAssembly backend; under Node it uses the native backend.

Use with WDK Core

The examples use the standalone manager because its shielded getter is separate from ordinary EVM account retrieval. Registering the manager with WDK core does not turn getAccount() into a Bermuda-account getter.

Do not assume WDK core's registered policies or middleware govern shielded accounts retrieved directly from this manager. The SDK has its own issuer-policy and compliance dependencies for its proof flow. Keep application authorization and confirmation around each fund-moving operation.

Dispose the Session

Call wallet.dispose() after all operations have finished, as the reader's finally block does. The manager disposes its EVM accounts, signers, and cached Bermuda accounts with the pinned WDK peers. Account disposal clears its stored Bermuda private-key fields and leaves the shared master EVM account to its owner.

Disposal does not delete persisted cache files, stop the SDK provider, erase every JavaScript or caller-held seed copy, or confirm/cancel a submitted transaction. Release application references when the session is finished. See resource lifecycle.

Next Steps

Need Help?