Monero JavaScript Library

A JavaScript library for creating Monero applications using RPC and WebAssembly bindings to monero v0.18.2.2 'Flourine Fermie'.

CSS Specific

Build Reproducibility

Build Reproducibility is about taking a particular version of the source of this project (input), and always getting the same compilation artifacts (output).

When this project is compiled, it produces a set of .js and .wasm files, which will then be embedded next to the source, in a .tgz file that npm can install.

This project tries to prove its build reproducibility by taking the files that will be embeded on the .tgz, hashing them together, and putting the hash inside the .tgz file, next to some instructions for the user to verify the reproducibility.

The instructions for the users simply ask them to clone the appropriate version of the repo and build a Docker image that reproduces the build+hashing process. The users can then compare the resulting hashes.

Summary

CSS Specific

Build Reproducibility

Build Reproducibility is about taking a particular version of the source of this project (input), and always getting the same compilation artifacts (output).

When this project is compiled, it produces a set of .js and .wasm files, which will then be embedded next to the source, in a .tgz file that npm can install.

This project tries to prove its build reproducibility by taking the files that will be embeded on the .tgz, hashing them together, and putting the hash inside the .tgz file, next to some instructions for the user to verify the reproducibility.

The instructions for the users simply ask them to clone the appropriate version of the repo and build a Docker image that reproduces the build+hashing process. The users can then compare the resulting hashes.

Summary

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

• Supports client-side wallets in Node.js and the browser using WebAssembly.
• Supports wallet and daemon RPC clients.
• 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 300 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

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 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 seed 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",
  seed: "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

1. cd your_project or mkdir your_project && cd your_project && npm init
2. npm install [email protected]
3. Add require("monero-javascript") to your application code.

Running in Node.js

Node.js 18 LTS is recommended and requires using the --no-experimental-fetch flag. Alternatively, Node.js 16 LTS works.

Building a browser application

1. Bundle your application code for a browser. See xmr-sample-app for an example project using webpack.
2. Copy assets from ./dist to your web app's build directory.

Using RPC servers:

1. Download and install Monero CLI.
2. Start monerod, 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 ./

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:

1. 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 3.1.10 && ./emsdk activate 3.1.10 && source ./emsdk_env.sh
   4. export EMSCRIPTEN=path/to/emsdk/upstream/emscripten (change for your system)
2. Clone monero-javascript repository: git clone --recursive https://github.com/monero-ecosystem/monero-javascript.git
3. cd monero-javascript
4. ./bin/update_submodules.sh
5. 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" ....
6. Download and install unbound 1.17.0 to your home directory (~).
7. ./bin/build_all.sh (install monero-project dependencies as needed for your system)

Running tests

1. Clone the project repository: git clone https://github.com/monero-ecosystem/monero-javascript.git
2. cd monero-javascript
3. Start RPC servers:
   1. Download and install Monero CLI.
   2. Start monerod, e.g.: ./monerod --testnet (or use a remote daemon).
   3. Start monero-wallet-rpc, e.g.: ./monero-wallet-rpc --daemon-address http://localhost:38081 --testnet --rpc-bind-port 28084 --rpc-login rpc_user:abc123 --wallet-dir ./
4. 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

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

Related projects

• monero-java
• monero-cpp
• xmr-sample-app - sample web application using monero-javascript
• 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.