This repository holds the Javascript source code for the Monero/CryptoNote cryptography and protocols, plus lightwallet functions which power the official [MyMonero](https://www.mymonero.com) apps.
There is also a chain of build scripts which is capable of building a JS module by transpiling a subset of Monero source code via emscripten, which relies upon static boost libs, for which there is also a script for building from source.
`monero_utils` contains Monero- and MyMonero-specific implementations, wrappers, and declarations, and the MyMonero JS and wasm implementations for the underlying cryptography behind Monero.
`monero_utils/MyMoneroCoreCpp.(js,wasm)` are produced by transpiling Monero core C++ code to JS via Emscripten (See *Building MyMoneroCoreCpp*). A Module instance is managed by `monero_utils/MyMoneroCoreBridge.js`.
A ready-made entrypoint for interacting with `MyMoneroCoreBridge` is located at `monero_utils/monero_utils.js` with usage `require("./monero_utils/monero_utils").then(function(monero_utils) { })` or `
Use the functions in the modules in `hostAPI` for convenience implementations of (a) networking to a MyMonero-API-compatible server, (b) constructing common request bodies, and (c) parsing responses.
For a working example usage of `hostAPI`, see [mymonero-app-js/HostedMoneroAPIClient](https://github.com/mymonero/mymonero-app-js/blob/master/local_modules/HostedMoneroAPIClient).
where `data` is the JSON response. Note you must pass in a `resolve`d `monero_utils` instance (see below for usage) so that such functions can remain synchronous without having to wait for the promise.
`__keyImageManaged` means that key images will be generated and then cached for a large performance boost for you. The caveat of this convenience is that you should make sure to call `DeleteManagedKeyImagesForWalletWith` on `monero_utils/monero_keyImage_cache_utils` (below) when you're done with them, such as on the teardown of a related wallet instance.
----
### `cryptonote_utils/mnemonic_languages`
It's not generally at all necessary to interact with this module unless you want to, e.g., construct a GUI that needs a list of support mnemonics.
In other words, if your app only needs to generate a mnemonic, you can avoid using this code module entirely by simply passing a language code (of "en", "en-US", "ja", "zh" etc) to the below `monero_utils` function which generates wallets.
-----
### `cryptonote_utils/nettype`
You'll need this module to construct the `nettype` argument for passing to various other functions.
Use these functions to derive additional state from transaction rows which were returned by a server and then parsed by `hostAPI`.
*`IsTransactionConfirmed(tx, blockchain_height)`
*`IsTransactionUnlocked(tx, blockchain_height)`
*`TransactionLockedReason(tx, blockchain_height)`
-----
### `monero_utils/monero_keyImage_cache_utils`
Use these functions to directly interact with the key image cache.
*`Lazy_KeyImage(…)` Generate a key image directly and cache it. Returns cached values.
*`DeleteManagedKeyImagesForWalletWith(address)` Call this to avoid leaking keys if you use any of the response parsing methods (above) which are suffixed with `__keyImageManaged`.
-----
### `monero_utils/monero_paymentID_utils`
Contains functions to validating payment ID formats. To generate payment IDs, see `monero_utils`.
-----
### `monero_utils/monero_requestURI_utils`
Functions for generating and parsing monero request URIs. Supports multiple currencies and formats.
-----
### `monero_utils/monero_sendingFunds_utils`
Contains convenience implementations such as `SendFunds(…)` for constructing arguments to `monero_utils/monero_utils:create_transaction`.
This function will likely make it into `mymonero-core-cpp` in the future.
One of the arguments to `SendFunds`, `preSuccess_nonTerminal_statusUpdate_fn`, supplies status updates via codes that can be translated into messages. Codes are located on `SendFunds_ProcessStep_Code` and messages are located at `SendFunds_ProcessStep_MessageSuffix`.
var decoded = monero_utils.decode_address("…", nettype);
```
#### Available functions
Each of these functions is implemented<sup>*</sup> in `monero_utils/MyMoneroCoreBridge.js`, which you access through `monero_utils/monero_utils.js`<sup>\*\*</sup>.
The arguments and return values for these functions are very explicitly called out by [MyMoneroCoreBridge.js](https://github.com/mymonero/mymonero-core-js/blob/develop/monero_utils/MyMoneroCoreBridge.js), so that will be the most complete documentation for the moment. Return values are all embedded within a JS dictionary unless they're singular values. Errors are thrown when functions are called via `monero_utils`.
<sup>* The functions' actual implementations are in WebAssembly which is produced via emscripten from exactly matching C++ functions in [mymonero-core-cpp](https://github.com/mymonero/mymonero-core-cpp). This allows core implementation to be shared across all platforms.</sup>
<sup>** for proper exception handling given that `MyMoneroCoreBridge` functions return `{ err_msg: }` rather than throwing</sup>
```
is_subaddress
```
```
is_integrated_address
```
```
new_payment_id
```
```
new__int_addr_from_addr_and_short_pid
```
```
new_fake_address_for_rct_tx
```
```
decode_address
```
```
newly_created_wallet
```
```
are_equal_mnemonics
```
```
mnemonic_from_seed
```
```
seed_and_keys_from_mnemonic
```
```
validate_components_for_login
```
```
address_and_keys_from_seed
```
```
generate_key_image
```
```
generate_key_derivation
```
```
derive_public_key
```
```
derive_subaddress_public_key
```
```
decodeRct
```
```
estimate_rct_tx_size
```
```
calculate_fee
```
```
estimated_tx_network_fee
```
##### Creating Transactions
These functions support Bulletproofs under the hood but don't take `bulletproof` as a parameter because that behavior is controlled by a hardcoded [`use_fork_rules` function](https://github.com/mymonero/mymonero-core-cpp/blob/master/src/monero_fork_rules.cpp#L49). Bulletproofs is not currently enabled.
```
create_signed_transaction
```
* Safe to call over IPC as it takes string rather than native JS objects as args.
```
create_signed_transaction__nonIPCsafe
```
* Takes JSBigInt rather than string args.
# Contributing
## QA
Please submit any bugs as Issues unless they have already been reported.
Suggestions and feedback are very welcome!
## Pull Requests
We'll merge nearly anything constructive. Contributors welcome and credited in releases.
We often collaborate over IRC in #mymonero on Freenode.
**All development happens off the `develop` branch like the Gitflow Workflow.**
There's no need to build monero_utils/MyMoneroCoreCpp as a build is provided, but if you were for example interested in adding a C++ function, you could use the information in this section to transpile it to JS.
Ensure you've [properly installed Emscripten](http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html) and exposed the Emscripten executables in your PATH, e.g.:
source ./emsdk_env.sh
### Boost for Emscripten
*Depends upon:* Emscripten SDK
Download a copy of the contents of the Boost source into `./contrib/boost-sdk/`.