README: api docs

6 years ago · e47c466151
parent 299c0c4bd6
commit e47c466151
1 changed files with 251 additions and 24 deletions
--- a/README.md
+++ b/README.md
@ -4,13 +4,14 @@

 1. Legal
 2. What's in This Repo?
-3. Library API Documentation
-4. Building MyMoneroCoreCpp from Scratch
+3. Usage

 ### Contributing

 1. QA
 2. Pull Requests
+3. Building MyMoneroCoreCpp from Scratch
+4. Contributors


 # Info
@ -29,18 +30,258 @@ There is also a chain of build scripts which is capable of building a JS module

 ### Contents 

-* `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) { })`
+`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`.

-* This readme is located at `README.md`, and the license is located at `LICENSE.txt`.
+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 `

+Many related utility functions and data structures are located throughout `monero_utils/`, `cryptonote_utils`, and `hostAPI`. Usage below.

-## Library API Documentation
+This readme is located at `README.md`, and the license is located at `LICENSE.txt`.

-*Coming soon*

+## Usage
+
+### `hostAPI`
+
+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).
+
+#### Examples
+
+```
+const endpointPath = "get_address_info"
+const parameters = net_service_utils.New_ParametersForWalletRequest(address, view_key__private)
+```
+
+```	
+monero_utils_promise.then(function(monero_utils) {
+	response_parser_utils.Parsed_AddressTransactions__keyImageManaged(
+		data,
+		address, view_key__private, spend_key__public, spend_key__private,
+		monero_utils,
+		function(err, returnValuesByKey) {
+			…
+		}
+	)
+})
+```
+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.
+
+#### Examples
+
+`const nettype = require('cryptonote_utils/nettype').network_type.MAINNET`
+
+-----
+### `cryptonote_utils/biginteger`
+
+Used extensively for managing Monero amounts in atomic units to ensure precision.
+
+#### Examples
+
+```
+const JSBigInt = require('../mymonero_core_js/cryptonote_utils/biginteger').BigInteger
+const amount = new JSBigInt('12300000')
+const amount_str = monero_amount_format_utils.formatMoney(amount)
+```
+
+-----
+### `cryptonote_utils/money_format_utils`
+
+It's not necessary to use this module directly. See `monero_utils/monero_amount_format_utils`.
+
+-----
+### `monero_utils/monero_amount_format_utils`
+
+```
+const monero_amount_format_utils = require("monero_utils/monero_amount_format_utils");
+const formatted_string = monero_amount_format_utils.formatMoney(a JSBigInt)
+```
+
+Functions: `formatMoneyFull`, `formatMoneyFullSymbol`, `formatMoney`, `formatMoneySymbol`, `parseMoney(str) -> JSBigInt`
+
+-----
+### `monero_utils/monero_txParsing_utils`
+
+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`.
+
+
+----
+### `monero_utils/monero_utils`
+
+#### Examples
+
+```
+	const mymonero = require("mymonero_core_js/index");
+	// or just "mymonero_core_js/monero_utils/monero_utils"
+	async function foo()
+	{
+		const monero_utils = await mymonero.monero_utils;
+		const nettype = mymonero.nettype_utils.network_type.MAINNET;
+		const decoded = monero_utils.address_and_keys_from_seed("…", nettype);
+		// read decoded.address_string
+		//
+	}
+	foo()
+```
+
+```
+	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.**

 ## Building MyMoneroCoreCpp from Scratch

@ -79,21 +320,6 @@ Or if you want to copy the build products to their distribution locations,
 * Execute `bin/archive-emcpp.sh`


-# 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.**

 ## Contributors

@ -105,4 +331,5 @@ We often collaborate over IRC in #mymonero on Freenode.

 * 🔒 `cryptochangement` Subaddress send & decode support; Initial tests

-* 💩 `henrynguyen5` Tests; Ledger support research
+* 💩 `henrynguyen5` Tests; Ledger support research
+