Skip to main content

Migrating from the WASM wrappers

The native bindings exist for the environments where the WASM wrappers cannot run: React Native and Expo apps, whose Hermes engine has no WebAssembly global. Browsers and Node.js should stay on the WASM path (JavaScript SDK) — it is unchanged.

What stays the same​

  • Function names. The exported surface mirrors the WASM wrappers one-for-one — makeDefaultAccountPrivkey, encodeOutputTransfer, encodeWitness, and the rest keep their names and parameter order.
  • Blob formats. Keys, inputs, outputs, witnesses and transactions are the same runtime SCALE bytes. A blob captured from @mintlayer/wasm-lib decodes identically through the native bindings, and vice versa.
  • Outputs. Byte-for-byte identical to @mintlayer/wasm-lib 1.4.0, verified in CI (see Overview).

What changes​

WASM (JavaScript)Native (Kotlin / Swift)
Uint8Array blobsByteArray / Data (convert at your RN bridge boundary)
JS numbers for amountsdecimal atom strings ("50000000000" for 500 ML)
npm package @mintlayer/wasm-libAAR (Android) / SPM package (iOS), see Installation
requires a WebAssembly globalnone; pure native libraries
error via thrown values / exceptionstyped BindingsException / BindingsError

The amounts change is the one that needs code review everywhere: JavaScript loses precision above 2⁵³, so the WASM wrappers accept JS numbers only for small values, while the native bindings take the exact 128-bit atom count as a decimal string. Convert once at the edge of your app (a formatAmount/parseAmount helper) and keep atoms as the in-app representation.

// Before (WASM): amount as a JS number of atoms
encodeOutputTransfer(50000000000, address, 'testnet');
// After (Kotlin): amount as a decimal atom string
encodeOutputTransfer("50000000000", address, Network.TESTNET)

Porting checklist​

  1. Swap the dependency: AAR for Android, MintlayerWalletBindings product for iOS (Installation).
  2. Update imports: org.mintlayer.wallet.bindings.* / import MintlayerWalletBindings; the function names are unchanged.
  3. Replace Uint8Array with ByteArray/Data at the React Native bridge (or native) boundary.
  4. Move amounts to decimal atom strings.
  5. Handle the typed errors instead of generic exceptions (Reference: Errors).
  6. Re-run your derivation against the public test vectors — the address tmt1qyxqfq37rra32sq6zhayqcpjwh4trc07mcfardwt must appear for the test mnemonic on testnet.

If your app used the high-level connect-sdk Client, note that the bindings are the primitive layer beneath it: there is no Client, no UTXO selection and no broadcast. Keep the connect-sdk patterns for chain data and port only the key/signing/encoding calls.