Monero JavaScript Library

A Node.js library for creating Monero applications using RPC and WebAssembly bindings to monero v0.17.2.3 'Oxygen Orion'.

Supports wallet and daemon RPC clients.
Supports client-side wallets in Node.js or the browser using WebAssembly.
Supports multisig, view-only, and offline wallets.
Wallet types are interchangeable by conforming to a common interface.
Uses a clearly defined data model and API specification intended to be intuitive and robust.
Query wallet transactions, transfers, and outputs by their properties.
Fetch and process binary data from the daemon (e.g. raw blocks).
Receive notifications when blocks are added to the chain or when wallets sync, send, or receive.
Over 280 passing Mocha tests.

Architecture
Sample code
Documentation
Using monero-javascript in your project
Building WebAssembly binaries from source
Running tests
Related projects
License
Donations

Architecture

Build Node.js or browser applications using RPC or WebAssembly bindings to monero-project/monero. Wallet implementations are interchangeable by conforming to a common interface, MoneroWallet.js.

Sample code

// import library
const monerojs = require("monero-javascript");

// connect to daemon
let daemon = await monerojs.connectToDaemonRpc("http://localhost:38081", "superuser", "abctesting123");
let height = await daemon.getHeight();            // 1523651
let feeEstimate = await daemon.getFeeEstimate();  // 1014313512
let txsInPool = await daemon.getTxPool();         // get transactions in the pool

// open wallet on monero-wallet-rpc
let walletRpc = await monerojs.connectToWalletRpc("http://localhost:38084", "rpc_user", "abc123");
await walletRpc.openWallet("sample_wallet_rpc", "supersecretpassword123");
let primaryAddress = await walletRpc.getPrimaryAddress(); // 555zgduFhmKd2o8rPUz...
let balance = await walletRpc.getBalance();               // 533648366742
let txs = await walletRpc.getTxs();                       // get transactions containing transfers to/from the wallet

// create wallet from mnemonic phrase using WebAssembly bindings to monero-project
let walletFull = await monerojs.createWalletFull({
  path: "sample_wallet_full",
  password: "supersecretpassword123",
  networkType: "stagenet",
  serverUri: "http://localhost:38081",
  serverUsername: "superuser",
  serverPassword: "abctesting123",
  mnemonic: "hefty value scenic...",
  restoreHeight: 573936,
});

// synchronize with progress notifications
await walletFull.sync(new class extends monerojs.MoneroWalletListener {
  onSyncProgress(height, startHeight, endHeight, percentDone, message) {
    // feed a progress bar?
  }
});

// synchronize in the background every 5 seconds
await walletFull.startSyncing(5000);

// receive notifications when funds are received, confirmed, and unlocked
let fundsReceived = false;
await walletFull.addListener(new class extends monerojs.MoneroWalletListener {
  onOutputReceived(output) {
    let amount = output.getAmount();
    let txHash = output.getTx().getHash();
    let isConfirmed = output.getTx().isConfirmed();
    let isLocked = output.getTx().isLocked();
    fundsReceived = true;
  }
});

// send funds from RPC wallet to WebAssembly wallet
let createdTx = await walletRpc.createTx({
  accountIndex: 0,
  address: await walletFull.getAddress(1, 0),
  amount: "250000000000", // send 0.25 XMR (denominated in atomic units)
  relay: false // create transaction and relay to the network if true
});
let fee = createdTx.getFee(); // "Are you sure you want to send... ?"
await walletRpc.relayTx(createdTx); // relay the transaction

// recipient receives unconfirmed funds within 5 seconds
await new Promise(function(resolve) { setTimeout(resolve, 5000); });
assert(fundsReceived);

// save and close WebAssembly wallet
await walletFull.close(true);

Documentation

JSDocs
API and model overview with visual diagrams
Mocha tests
Installing prerequisites
Getting started part 1: creating a Node.js application
Getting started part 2: creating a web application
Creating wallets
The data model: blocks, transactions, transfers, and outputs
Getting transactions, transfers, and outputs
Sending funds
Multisig wallets
View-only and offline wallets
HTTPS and self-signed certificates

Using monero-javascript in your project

cd your_project or mkdir your_project && cd your_project && npm init
npm install monero-javascript@0.5.6
Add require("monero-javascript") to your application code.
If building a browser application, copy assets from ./dist to your web app's build directory as needed.

If using RPC servers:

Download and install Monero CLI.
Start monero-daemon-rpc, e.g.: ./monerod --stagenet (or use a remote daemon).
Start monero-wallet-rpc, e.g.: ./monero-wallet-rpc --daemon-address http://localhost:38081 --stagenet --rpc-bind-port 38084 --rpc-login rpc_user:abc123 --wallet-dir ./

Building WebAssembly binaries from source

This project uses WebAssembly to package and execute Monero's source code for use in a browser or other WebAssembly-supported environment.

Compiled WebAssembly binaries are committed to ./dist for convenience, but these files can be built independently from source code:

Install and activate emscripten.
1. Clone emscripten repository: git clone https://github.com/emscripten-core/emsdk.git
2. cd emsdk
3. git pull && ./emsdk install latest-upstream && ./emsdk activate latest-upstream && source ./emsdk_env.sh
4. export EMSCRIPTEN=path/to/emsdk/upstream/emscripten (change for your system)
Clone monero-javascript repository: git clone https://github.com/monero-ecosystem/monero-javascript.git
cd monero-javascript
./bin/update_submodules.sh
Modify ./external/monero-cpp/external/monero-project/src/crypto/wallet/CMakeLists.txt from set(MONERO_WALLET_CRYPTO_LIBRARY "auto" ... to set(MONERO_WALLET_CRYPTO_LIBRARY "cn" ....
./bin/build_all.sh (install monero-project dependencies as needed for your system)

Running tests

Clone the project repository: git clone https://github.com/monero-ecosystem/monero-javascript.git
cd monero-javascript
Start RPC servers:
1. Download and install Monero CLI.
2. Start monero-daemon-rpc, e.g.: ./monerod --stagenet (or use a remote daemon).
3. Start monero-wallet-rpc, e.g.: ./monero-wallet-rpc --daemon-address http://localhost:38081 --stagenet --rpc-bind-port 38084 --rpc-login rpc_user:abc123 --wallet-dir ./
Configure the appropriate RPC endpoints, authentication, and other settings in TestUtils.js (e.g. WALLET_RPC_CONFIG and DAEMON_RPC_CONFIG).

Running tests in Node.js

Run all tests: npm test
Run tests by their description, e.g.: npm run test -- --grep "Can get transactions"

Running tests in a browser

Start monero-wallet-rpc servers used by tests: ./bin/start_wallet_rpc_test_servers.sh
In another terminal, build browser tests: ./bin/build_browser_tests.sh
Access http://localhost:8080/tests.html in a browser to run all tests

Related projects

monero-java
monero-cpp
monerostresstester.com - repeatedly sends txs to self to stress test the network (under development)
xmr-sample-app - sample web app template (under development)
monerowebwallet.com - open-source, client-side web wallet (under development)

License

This project is licensed under MIT.

Donations

If this library brings you value, please consider donating.

46FR1GKVqFNQnDiFkH7AuzbUBrGQwz2VdaXTDD4jcjRE8YkkoTYTmZ2Vohsz9gLSqkj5EM6ai9Q7sBoX4FPPYJdGKQQXPVz

monero-javascriptA Node.js library for using Monero