Crypto wallets

The com.codename1.crypto packages hold everything a wallet, an exchange or a payment backend needs to work with Ethereum and the other EVM chains, Bitcoin, and Solana. That covers recovery phrases and key derivation, addresses, transactions, signing, the node APIs that broadcast transactions and read balances, and price feeds. There are no third-party libraries to add, and the same classes run in the app and in a Codename One backend.

The heavy parts run as native code wherever the platform allows it: secp256k1, Schnorr, Ed25519, the hashes and the PBKDF2 behind a recovery phrase. Elsewhere they fall back to an optimized pure-Java engine. A benchmark in CI compares every kernel against libsecp256k1, libsodium, OpenSSL and BouncyCastle on the same machine, and fails a pull request whose crypto changes fall behind.

The packages, from the bottom up:

A handful of algorithms do all the work underneath, and the names come up throughout this chapter and in every chain’s documentation. You never call most of them directly, but knowing what each one is for makes the rest easier to follow, and it explains why their speed matters.

Elliptic curves and signatures. A private key is a large random number. The public key is a point on an elliptic curve, computed from it in a way that’s easy forward and infeasible to reverse. A signature proves that the holder of the private key approved a message, and anyone with the public key can check it.

Verifying is the expensive direction. A wallet signs a handful of transactions, but a node, an exchange or an indexer verifies every signature it receives, which is where batches and the GPU come in.

Hash functions. A hash turns any input into a short fixed-size fingerprint. Changing one bit of the input changes the whole fingerprint, and nobody can find two inputs with the same one.

A Merkle tree hashes a list of items in pairs, then hashes the pairs, until one root remains. Changing any item changes the root, so a block header commits to all its transactions in 32 bytes. Building a level of one is a batch of independent hashes, which is what the Merkle rows in the benchmarks measure.

From a recovery phrase to keys. BIP-39 turns random bytes into a phrase of 12 or 24 words and back. It stretches the phrase into a 64-byte seed with PBKDF2, which runs HMAC-SHA512 2,048 times on purpose, so that guessing phrases is slow for an attacker. It’s also the one step a user waits for when they restore a wallet. BIP-32 derives a tree of keys from that seed, so one phrase yields every account on every chain, and SLIP-10 does the same for Ed25519. A derivation path such as m/44'/60'/0'/0/0 names one key in the tree.

Engines, kernels, and batches. The public classes are plain Java and the same everywhere. Underneath, a crypto engine supplies the compute-heavy kernels, which are the signature and hash operations above. On iOS, macOS, Android, Windows, Linux and a production backend the engine is native C, which uses the processor’s vector and hash instructions where it has them. On the JVM and in the browser it’s an optimized pure-Java engine. A batch hands many independent operations to the engine at once, so it can spread them across every CPU core and, for large batches, the GPU.

A wallet starts as a recovery phrase. Every key on every chain is derived from it, so the phrase is the only thing a user ever needs to back up.

Mnemonic.isValid checks the words against the English list and verifies the checksum the last word carries, so a typo is caught before it turns into an empty wallet with a different address.

Wallet answers addresses on the paths other wallets use. A phrase restored here shows the same accounts it shows in MetaMask, Electrum, Sparrow or Phantom:

For Bitcoin, the purpose picks the address type: Wallet.BIP44 for legacy 1…​ addresses, BIP49 for P2SH-wrapped SegWit, BIP84 for native SegWit bc1q…​ and BIP86 for Taproot bc1p…​. The same network object also selects testnet, signet, or regtest.

The pattern is the same on every chain. You read what the transaction needs from a node, build it, sign it on the device, and hand the signed bytes back to the node. Private keys never leave the Signer.

The node clients are blocking calls over an RpcTransport. In the app that’s NetworkTransport, which goes through the NetworkManager queue and keeps the UI responsive when called from the EDT. In a backend, com.codename1.backend.WebRpcTransport does the same over the backend’s HTTP client. A provider’s API key goes in a header: new NetworkTransport().header("Authorization", "Bearer …​").

Amounts are UInt256, an exact unsigned 256-bit integer, so wei never passes through a double. parseUnits("0.01", 18) and formatUnits(18) convert to and from the decimal amount a person reads. suggestFees sets the fee cap at twice the next base fee plus the tip, which stays valid through several full blocks. The chain ID comes from the node and goes into the signature, so a transaction signed for one chain can’t be replayed on another.

Token transfers, contract calls and EIP-712 typed data use the same flow. Look at Erc20, Abi and TypedData in crypto.evm, and at Wallet.signTypedData and Wallet.personalSign for sign-in messages.

A Bitcoin transaction spends earlier outputs ("coins") rather than debiting a balance, and a signer has to know the value of each coin it signs for. A PSBT (BIP-174) carries that information, and it’s also the format hardware wallets and multisig co-signers exchange:

EsploraClient speaks the REST API of mempool.space and blockstream.info, or of your own Esplora server. getFeeEstimates returns sats per virtual byte by confirmation target. Multiply that by the size of the transaction to get feeSats. Every output the snippet doesn’t spend is paid as a fee, so a real wallet adds a change output back to one of its own addresses.

Wallet.signPsbt(psbt) signs any input whose BIP-32 origin matches the wallet’s own fingerprint. That lets a PSBT built elsewhere, by a coordinator or a watch-only wallet, be signed without being told which keys to use. Taproot inputs are signed with BIP-340 Schnorr signatures automatically.

Amounts are in lamports (a billionth of a SOL). A blockhash expires after about a minute, so fetch it right before signing. TokenProgram builds SPL token transfers, and SolanaAddress.associatedTokenAddress finds the account a token is held in. ComputeBudget.setComputeUnitPrice adds a priority fee when the network is busy.

PriceFeed answers one question: the price of one asset in another. CoinGeckoFeed works without a key at the public rate limit, and takes a demo or pro key for more. JsonPriceFeed turns any JSON price API into a feed from a URL template and the path to the price. Wrap either in CachingPriceFeed, so a screen that prices twenty balances makes one request:

A cached quote stays fresh for the first window. After that it’s still returned when a refresh fails, until the second window ends. That keeps a balance screen useful through a brief outage without showing a price that’s hours old.

A backend that scans a block for deposits, or an indexer that checks every transaction it stores, verifies thousands of signatures at a time. CryptoBatch takes them as arrays and answers one boolean per entry:

With native kernels the whole batch crosses into native code once and runs on every CPU core, which makes it several times faster than the same calls in a loop. verifySchnorr, verifyEd25519, sha256 and keccak256 work the same way. Every entry gets exactly the answer a single call would give, and a malformed entry, such as a key that doesn’t parse, is invalid rather than an exception, so one bad entry never stops the rest.

For the largest batches, every method also has a packed form that takes flat arrays at a fixed stride: 32-byte hashes one after another, 64-byte signatures one after another, and the public keys likewise, with one result byte per entry. On a native target the kernels read those arrays in place, so nothing is copied and no object is created per entry. Allocate them with Simd.get().allocByte(int) and they’re also aligned for the vector units:

On iOS, macOS, Android, Windows and Linux, a large enough batch is shared between the CPU cores and the GPU, through Metal on Apple platforms and Vulkan elsewhere. The split follows the measured speed of each: the CPU and the GPU work on their parts at the same time, and a device whose GPU is slower than its CPU keeps the whole batch on the CPU. In a browser the GPU is reached through WebGPU, with the same kernels. The GPU only ever sees public data, meaning signatures, public keys and messages, and never a private key. Your code doesn’t change, and the results are the same either way.

Every CryptoBatch method has an asynchronous form with Async added to its name. It takes the same arguments plus a CryptoBatch.Callback, returns at once, and runs the batch on a background thread:

In the app the callback runs on the EDT and can update the UI directly. In a backend it runs on the thread that did the work. The arguments are checked before the call returns, so a malformed batch, such as arrays of different lengths, throws right away instead of reaching the callback. The callback gets exactly what the synchronous form would have returned, or the exception it would have thrown. A packed form hands back the results array you passed in. The batch reads your arrays directly rather than copying them, so until the callback runs they belong to the batch: change one before then and you change what’s being verified.

In a browser, use the asynchronous forms. A large batch there goes to the GPU through WebGPU, which answers only asynchronously. The synchronous form still works, but it holds the calling thread until the GPU is done, and on the EDT that means the UI waits too. When the browser has no WebGPU adapter, both forms run on the CPU. The GPU kernels are about 460 KB of JavaScript, and they’re included only in apps that call CryptoBatch, loaded the first time a batch is large enough to use them.

Every operation is benchmarked against the library a project would otherwise use for it, in the same process run, on the same machine. The figures below are ratios: 2.00x means Codename One did twice the work of the reference library in the same time, and anything above 1.00x is faster. Ratios stay steady from one machine to the next where absolute speeds don’t, so they’re also what CI checks. A run fails when any ratio drops below the floor recorded for it in scripts/crypto-bench/floors.json.

These numbers come from an Apple M4 Max (12 performance cores, 40-core GPU), and the Android ones from an arm64 API 36 emulator on the same machine.

The simulator, JavaSE desktop apps and the backend in development run the portable Java implementation. It’s compared with BouncyCastle 1.84 and, for Ed25519, with the JDK’s own provider, on JDK 25. CI runs the same benchmark on JDK 17.

Ed25519 verification rewrites its check with two scalars of half the length, found by a lattice reduction, so the multiplication needs half the doublings. The rewrite gives exactly the answer of the direct check for every input, including keys with a small-order component. On x86-64 the field multiplication also takes a Karatsuba split, which needs 75 products instead of 100. arm64 has the registers to keep the direct form faster, so each architecture gets the form that’s faster on it. The CI runners are x86-64, and they’re held to the same floors.

On iOS, macOS, Windows, Linux and the production backend the same operations run as C, compared with Bitcoin Core’s libsecp256k1 for the secp256k1 curve and OpenSSL 3.6 for everything else, both built with the same compiler and flags.

A batch runs on every core, so it’s measured against the reference library verifying the same entries one at a time, which is what an application without CryptoBatch would do. The figures are batches of 1,024 signatures, or Merkle levels of 4,096 nodes, per second:

Android has no curve secp256k1 in its platform, so apps there would otherwise ship BouncyCastle. The table shows both the native kernels and the portable Java implementation, each against BouncyCastle on the same device. The two engines ran in turn, each beside its own BouncyCastle run, so each ratio is against the BouncyCastle figure from its own run; the column shows the one from the native run, and the two agree to within 4%.

SHA-256 and the BIP-39 seed go through the platform’s own native implementation in both columns, which is why they match. With the native kernels, RIPEMD-160 is the one row where BouncyCastle stays ahead; it’s hashed once per Bitcoin address, so it’s never the bottleneck. The portable Java column trails BouncyCastle on Ed25519 and RIPEMD-160 and matches it on Keccak-256.

A GPU verifies signatures in parallel by the thousand, but each entry first needs some preparation on the CPU, and the GPU’s work has to be dispatched and collected. A batch is therefore split, with the CPU cores and the GPU each taking a share in proportion to their measured speed, and a batch smaller than the crossover stays on the CPU. With Metal on the M4 Max:

The chart shows the signature rows; Keccak-256 is measured in bytes rather than signatures, so it appears only in the table.

On this machine the gain is modest, because sixteen CPU cores with vector units are already fast. The split is worked out from the speeds measured on each device, so a GPU that’s strong relative to its CPU takes a larger share, and one that’s slower takes none. SHA-256 has no GPU row: in this run no SHA-256 batch reached the GPU’s minimum size, so they all ran on the CPU.

The JavaScript port runs the portable Java implementation, translated to JavaScript. Large batches go to the GPU through WebGPU and arrive through the asynchronous forms. In headless Chromium on the same machine, with batches of 4,096 signatures:

In the browser most of the time a WebGPU batch takes is the preparation in JavaScript, not the GPU work, and the browser’s figures move more from run to run than the native ones: across three runs SHA-256 on WebGPU ranged from 4 to 34 MB/s, and in the slowest it trailed the CPU. The answers never differed: the first run compared a sample of the signatures, and the runs after it compared every entry and every hash. Given records prepared in advance, the kernels alone verified about 164,000 ECDSA, 119,000 Schnorr and 146,000 Ed25519 signatures a second there.

The chart puts the ways a signature can be verified side by side, on a logarithmic scale. They don’t measure the same thing: the browser bars are batches on one JavaScript thread, the JVM and native bars are one signature at a time on one core, and the last bar is a native batch across every core and the GPU. Read it as what each setup delivers, not as one benchmark run across platforms.

The harnesses are in scripts/crypto-bench and scripts/crypto-gpu of the Codename One repository:

Each prints the compiler, JDK and reference library versions above its numbers. scripts/crypto-bench/charts.py draws the two charts above from the saved results.

Whoever holds the recovery phrase holds the funds. Decide where it lives before you write the first screen.

On the device, in a vault. VaultSigner keeps the phrase sealed in a vault (see "Vaults: One password, every device" in the security chapter) and opens it only while the vault is unlocked, by biometrics or the vault password. It works anywhere Wallet expects a signer:

This is the model for a self-custody wallet. A lost device loses nothing as long as the user kept the phrase, and revealMnemonic shows it again for a backup. A signer whose vault is locked throws rather than signing, so a stolen, locked phone can’t move funds.

On a server, behind your own controls. An exchange or a custodial app derives its deposit addresses and signs its withdrawals in the backend, where the same classes run. Keep the phrase out of the database and the source tree: load it from a secret store or an HSM at startup, and keep withdrawals behind an approval step. The Bastion sample does exactly this. Its implementor’s guide walks through hot and deposit wallets, confirmation depth and reorg handling.

SeedSigner holds the derived master key in memory. Call destroy() when you’re done with it, and the key bytes are overwritten. Strings can’t be wiped, which is why VaultSigner.revealMnemonic answers a char[].