MyMonero Core C++

1. What's in this Repo?
2. Setup
3. Usage
4. Testing
5. Pull Requests
6. Developing
7. Contributors
8. Embedding the C++
9. API

What's in This Repo?

This repository holds the C++ source code for the Monero/CryptoNote cryptography and protocols, plus lightwallet functions which power the official MyMonero apps.

A primary goal for this repository is its future convergence and reimplementation with an essential Monero core library.

Contents

• contrib/monero-core-custom is a Git submodule which contains a curated subset of the official Monero C/C++ source code, eventually to be replaced by new official Monero core repo

• src contains all the custom code written for this repo.

  • serial_bridge_index contains a central JSON interface to a set of central mymonero-core functions, documented below.

• This readme is located at README.md, and the license is located at LICENSE.txt. All source code copyright © 2014-2018 by MyMonero. All rights reserved.

Dependencies

• (to use included shell scripts) cmake

• Boost 1.58 library components

  • system

  • thread

  • If running tests: unit_test_framework

• monero-core-custom (see "Setup")

Setup

• Run bin/update_submodules

Usage

Simply embed the relevant code in your application, generally via CMake. See CMakeLists.txt for required files.

One example usage of this code is its transpilation into wasm and JS by mymonero-core-js.

Testing

• Run bin/buildAndRun_tests to execute Boost test cases.

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 and relevant. There are lots of items slated for development or happening concurrently, so get in touch and we'll let you know if anyone's working on it. We often collaborate over IRC in #mymonero on Freenode.

Contributors credited in releases.

All development happens off the develop branch like the Gitflow Workflow.

Developing

• If you use a Mac and want to develop within Xcode, run bin/genXcodeProj to generate ./xcode/TEST.xcodeproj. Once opened, its build target can be switched from ALL_BUILD to test_all, from which a Build & Run will display test results in the console.

• Branches and PRs should be made from and to the develop branch, which gets merged to master for tagged releases

Authors, Contributors, and Advisors

• 💫 Paul Shapiro Lead dev, maintainer

• 🍄 luigi1111

• 🤵 vtnerd C++ & Monero advisory

• 🐮 moneromooo-monero Major Monero contributor; Advisory

• 🦁 ndorf C++ & Monero expertise, architecture, code contributions

• 🏍 gutenye Code contributions

Embedding the C++

If you want to embed the C++ or build the source in your own project, please take note of the following:

• slow-hash.c must be compiled with -maes

• The Monero source, a slightly modified version of which is a dep of this project, can only be built on versions of iOS >= 9 due to required support for thread_local as used by threadpool.cpp.

• Not all Monero .cpp files which are in monero-core-custom must be included for mymonero-core-cpp - such as when their symbols are not required by any code called by this project. See CMakeLists.txt for a list of files required for compilation.

• If you only want to call the C++ directly without using serial_bridge_index (described below), then that file-pair does not need to be included in your build. (See mymonero-app-ios link)

API

Notes:

• If you are implementing the below-described Send routine yourself (examples: JS, Swift), you should:
  • implement the necessary re-entry logic if step2 indicates reconstruction required, and
  • (optional) construct the err_msg if the error code indicates not enough spendable balance.

C++

Coming soon

For examples see src/serial_bridge_index.cpp and mymonero-app-ios/MyMoneroCore_ObjCpp.mm.

JSON

src/serial_bridge_index exposes this project's core library functions. Each bridge function takes a string-serialized JSON object as an argument and returns a string-serialized JSON object.

Usage of each of these JSON-bridge functions is demonstrated in tests/test_all.cpp.

When they fail, some of these functions return only a key-value err_msg.

Argument and return value data types

• Some args must be passed as strings, such as uint64 args like indexs and amounts.

• Some boolean return values may be sent (by Boost) in JSON as strings instead, called BoolString below ( e.g. "false").

• Network type is sent as a string (NettypeString below), which can be obtained via serial_bridge::string_from_nettype().

Compressing / reducing size of key names could be a significant optimization, as could a migration to msgpack.

Parsing Addresses

decode_address

• Args: nettype_string: NettypeString, address: String

• Returns: err_msg: String OR pub_spendKey_string: String, pub_viewKey_string: String, paymentID_string: String, and isSubaddress: Boolstring

is_subaddress

• Args: nettype_string: NettypeString, address: String

• Returns: err_msg: String OR retVal: Boolstring

is_integrated_address

• Args: nettype_string: NettypeString, address: String

• Returns: err_msg: String OR retVal: Boolstring

Parsing and Creating Wallets

newly_created_wallet

• Args: nettype_string: NettypeString, locale_language_code: String

• Returns: err_msg: String OR mnemonic_string: String, mnemonic_language: WordsetNameString, sec_seed_string: String, address_string: String, pub_spendKey_string: String, pub_viewKey_string: String, sec_viewKey_string: String, and sec_spendKey_string: String

are_equal_mnemonics

• Args: a: String, b: String

• Returns: err_msg: String OR retVal: Boolstring

mnemonic_from_seed

• Args:

  • seed_string: String
  • wordset_name: WordsetNameString returned as mnemonic_language by seed_and_keys_from_mnemonic and newly_created_wallet

• Returns: err_msg: String OR retVal: String

seed_and_keys_from_mnemonic

• Args: nettype_string: NettypeString, mnemonic_string: String

• Returns: err_msg: String OR mnemonic_language: WordsetNameString, sec_seed_string: String, address_string: String, pub_spendKey_string: String, pub_viewKey_string: String, sec_viewKey_string: String, and sec_spendKey_string: String

validate_components_for_login

• Args: nettype_string: NettypeString, address_string: String, sec_viewKey_string: String, sec_spendKey_string: Optional<String>, seed_string: Optional<String>

• Returns: err_msg: String OR pub_spendKey_string: String, pub_viewKey_string: String, isInViewOnlyMode: Boolstring, and isValid: Boolstring

address_and_keys_from_seed

• AKA create_address in legacy mymonero-core-js

• Args: nettype_string: NettypeString, seed_string: String

• Returns: err_msg: String OR address_string: String, pub_spendKey_string: String, pub_viewKey_string: String, sec_viewKey_string: String, and sec_spendKey_string: String

Producing Misc. Values

new_integrated_address

• Args: nettype_string: NettypeString, short_pid: String, address: String

• Returns: err_msg: String OR retVal: String

new_payment_id

• Args: empty object

• Returns: err_msg: String OR retVal: String

generate_key_image

• Args: sec_viewKey_string: String, sec_spendKey_string: String, pub_spendKey_string: String, tx_pub_key: String, out_index: UInt32String

• Returns: err_msg: String OR retVal: String

generate_key_derivation

• Args: pub: String, sec: String

• Returns: err_msg: String OR retVal: String

derivation_to_scalar

• Args: derivation: String, output_index: UInt32String

• Returns: err_msg: String OR retVal: String

derive_public_key

• Args: derivation: String, pub: String, out_index: UInt32String

• Returns: err_msg: String OR retVal: String

derive_subaddress_public_key

• Args: derivation: String, output_key: String, out_index: UInt32String

• Returns: err_msg: String OR retVal: String

decodeRct, decodeRctSimple

• Args: i: UInt32String, sk: String, rv: DecodeRCT_RV where

  • DecodeRCT_RV: Dictionary with type: RCTTypeIntString, ecdhInfo: [DecodeRCT_ECDHInfo], outPk: [DecodeRCT_OutPK]

    • RCTTypeIntString: String corresponding to values in rct::RCTType*

    • DecodeRCT_ECDHInfo: Dictionary with amount: String, mask: String

    • DecodeRCT_OutPK: Dictionary with mask: String

e.g.

{"i":"1","sk":"9b1529acb638f497d05677d7505d354b4ba6bc95484008f6362f93160ef3e503","rv":{"type":"1","ecdhInfo":[{"mask":"3ad9d0b3398691b94558e0f750e07e5e0d7d12411cd70b3841159e6c6b10db02","amount":"b3189d8adb5a26568e497eb8e376a7d7d946ebb1daef4c2c87a2c30b65915506"},{"mask":"97b00af8ecba3cb71b9660cc9e1ac110abd21a4c5e50a2c125f964caa96bef0c","amount":"60269d8adb5a26568e497eb8e376a7d7d946ebb1daef4c2c87a2c30b65915506"},{"mask":"db67f5066d9455db404aeaf435ad948bc9f27344bc743e3a32583a9e6695cb08","amount":"b3189d8adb5a26568e497eb8e376a7d7d946ebb1daef4c2c87a2c30b65915506"}],"outPk":[{"mask":"9adc531a9c79a49a4257f24e5e5ea49c2fc1fb4eef49e00d5e5aba6cb6963a7d"},{"mask":"89f40499d6786a4027a24d6674d0940146fd12d8bc6007d338f19f05040e7a41"},{"mask":"f413d28bd5ffdc020528bcb2c19919d7484fbc9c3dd30de34ecff5b8a904e7f6"}]}}

• Returns err_msg: String OR amount: String and mask: String

Fees

estimated_tx_network_fee

Useful for displaying an estimated fee – To obtain exact fees, see "Creating and Sending Transactions"

• Args:

  • fee_per_b: UInt64String
  • priority: UInt32String
  • fork_version: UInt8String

• Returns: retVal: UInt64String

estimate_rct_tx_size

• Args:

  • n_inputs: UInt32String
  • mixin: UInt32String
  • n_outputs: UInt32String
  • extra_size: UInt32String
  • bulletproof: BoolString

• Returns: retVal: UInt32String

Creating and Sending Transactions

As mentioned, implementing the Send procedure without making use of one of our existing libraries or examples involves two bridge calls surrounded by server API calls, and mandatory reconstruction logic, and is simplified by various opportunities to pass values directly between the steps.

The values which must be passed between functions have (almost entirely) consistent names, simplifying integration. The only current exception is the name of the explicit fee_actually_needed which should be passed to step1 as the optional passedIn_attemptAt_fee after being received by calling step2 (see below).

Examples

• JS implementation of SendFunds
• JS implementation of JSON bridge calls - note err_code handling in step1 and comments

Shared JSON types

• UnspentOutput: Dictionary with

  • amount: UInt64String
  • public_key: String
  • rct: Optional<String>
  • global_index: UInt64String
  • index: UInt64String
  • tx_pub_key: String

• CreateTransactionErrorCode: UInt32String defined in monero_transfer_utils.hpp; to remain stable within major versions

send_step1__prepare_params_for_get_decoys

• Args:

  • sending_amount: UInt64String
  • is_sweeping: BoolString
  • priority: UInt32String of 1–4
  • fee_per_b: UInt64String
  • fee_mask: UInt64String
  • fork_version: UInt8String
  • unspent_outs: [UnspentOutput] - fully parsed server response
  • payment_id_string: Optional<String>
  • passedIn_attemptAt_fee: Optional<UInt64String>

• Returns:

  • err_code: CreateTransactionErrorCode==needMoreMoneyThanFound(90)
  • err_msg: String
  • required_balance: UInt64String
  • spendable_balance: UInt64String

  OR

  • err_code: CreateTransactionErrorCode!=needMoreMoneyThanFound
  • err_msg: String

  OR

  • mixin: UInt32String use this for requesting random outputs before step2
  • using_fee: UInt64String
  • change_amount: UInt64String
  • using_outs: [UnspentOutput] passable directly to step2
  • final_total_wo_fee: UInt64String

send_step2__try_create_transaction

• Args:

  • from_address_string: String

  • sec_viewKey_string: String

  • sec_spendKey_string: String

  • to_address_string: String

  • final_total_wo_fee: UInt64String returned by step1

  • change_amount: UInt64String returned by step1

  • fee_amount: UInt64String returned by step1

  • priority: UInt32String of 1–4

  • fee_per_b: UInt64String

  • fee_mask: UInt64String

  • fork_version: UInt8String

  • using_outs: [UnspentOutput] returned by step1

  • mix_outs: [MixAmountAndOuts] defined below

  • unlock_time: UInt64String

  • nettype_string: NettypeString

  • payment_id_string: Optional<String>

    • MixAmountAndOuts: Dictionary decoys obtained from API call with
      • amount: UInt64String
      • outputs: [MixOut] where
        • MixOut: Dictionary with
          • global_index: UInt64String
          • public_key: String
          • rct: Optional<String>

  • Returns:

    • tx_must_be_reconstructed: BoolString==true
    • fee_actually_needed: UInt64String pass this back to step1 as passedIn_attemptAt_fee

    OR

    • err_msg: String

    OR

    • tx_must_be_reconstructed: Boolstring!=true
    • serialized_signed_tx: String
    • tx_hash: String
    • tx_key: String