Monero JavaScript Library
A Node.js library for creating Monero applications using RPC and WebAssembly bindings to monero v0.17.3.0 '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.
Table of contents
- 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
- Connection manager
- HTTPS and self-signed certificates
Using monero-javascript in your project
cd your_project
ormkdir your_project && cd your_project && npm init
npm install monero-javascript@0.6.4
- 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.
- Clone emscripten repository:
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
git pull && ./emsdk install latest-upstream && ./emsdk activate latest-upstream && source ./emsdk_env.sh
export EMSCRIPTEN=path/to/emsdk/upstream/emscripten
(change for your system)
- Clone emscripten repository:
- 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" ...
toset(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:
- 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 ./
- Configure the appropriate RPC endpoints, authentication, and other settings in TestUtils.js (e.g.
WALLET_RPC_CONFIG
andDAEMON_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)
- monero-deposit-scanner - scan for incoming deposits to an address using a view key (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