ots.hpp

Go to the documentation of this file.

#pragma once
 
#include "ots-exceptions.hpp"
#include <memory>
#include <string>
#include <vector>
#include <array>
#include <map>
#include <utility>
 
#ifndef DEFAULT_MAX_ACCOUNT_DEPTH
#define DEFAULT_MAX_ACCOUNT_DEPTH 10
#endif
 
#ifndef DEFAULT_MAX_INDEX_DEPTH
#define DEFAULT_MAX_INDEX_DEPTH 100
#endif
 
#define OUTPUT_EXPORT_FILE_MAGIC "Monero output export\004"
 
namespace ots {
 
    enum class Network {
        MAIN,
        TEST,
        STAGE,
        // WARNING: On extending the network types, the cryptonoteNetwork function in ots-internal.hpp needs to be updated, or at least reviewed.
        // WARNING: keep OTS_NETWORK in sync with this enum, too!
    };
 
    enum class AddressType {
        Standard,
        SubAddress,
        Integrated
        // WARNING: Keep OTS_ADDRESS_TYPE in sync with this enum!
    };
 
    enum class SeedType {
        Monero,
        Polyseed
        // WARNING: Keep OTS_SEED_TYPE in sync with this enum!
    };
 
    // Forward declarations
    class Seed;
    class Address;
    class Wallet;
    class Account;
    class KeyStore;
    class PolyseedKeyStore;
    class WipeableString;
    class SeedIndices;
    class MoneroSeed;
    struct KeyStoreDeleter { // for std::unique_ptr, if not it will not compile
            void operator()(KeyStore* p) const;
    };
    struct PolyseedKeyStoreDeleter { // for std::unique_ptr, if not it will not compile
            void operator()(PolyseedKeyStore* p) const;
    };
    class Account;
    struct AccountDeleter { // for std::unique_ptr, if not it will not compile
            void operator()(Account* p) const;
    };
    class PolyseedKeyStore;
    class TxDescription;
    class TxWarning;
 
    // Type aliases
    using key_handle_t = size_t;
    using seed_handle_t = size_t;
 
    class SeedLanguage {
        public:
            [[nodiscard]] const std::string& name() const;
 
            [[nodiscard]] const std::string& englishName() const;
 
            [[nodiscard]] const std::string& code() const;
 
            [[nodiscard]] bool supported(SeedType type = SeedType::Monero) const;
 
            [[nodiscard]] bool isDefault(SeedType type = SeedType::Monero) const;
 
            [[nodiscard]] int index(SeedType type = SeedType::Monero) const noexcept;
 
            bool operator==(const SeedLanguage& other) const;
 
            bool operator==(SeedLanguage& other) const;
 
            bool operator==(const std::string& code) const;
 
            operator const std::string&() const;
 
            static const SeedLanguage& fromName(const std::string& name);
 
            static const SeedLanguage& fromEnglishName(const std::string& name);
 
            static const SeedLanguage& fromCode(const std::string& code);
 
 
            static const std::vector<std::reference_wrapper<const SeedLanguage>> list();
 
            static const std::vector<std::reference_wrapper<const SeedLanguage>> listFor(SeedType type);
 
            static const SeedLanguage& defaultLanguage(SeedType type = SeedType::Monero);
 
            static void setDefaultLanguage(SeedType type, const SeedLanguage& language);
 
        private:
            static std::vector<SeedLanguage> s_list;
            static std::map<SeedType, std::reference_wrapper<const SeedLanguage>> s_default;
            std::string m_code;
            std::string m_name;
            std::string m_englishName;
            std::map<SeedType, bool> m_supported;
            std::map<SeedType, int> m_index;
    };
 
    class Seed {
        public:
            virtual ~Seed() = default;
 
            virtual const WipeableString phrase(const SeedLanguage& language, const std::string& password = "") const = 0;
 
            virtual const SeedIndices indices(const std::string& password = "") const = 0;
 
            virtual const std::string& fingerprint() const noexcept;
 
            virtual const Address& address() const noexcept;
 
            virtual const uint64_t timestamp() const noexcept;
 
            virtual const uint64_t height() const noexcept;
 
            virtual inline const Network& network() const noexcept { return m_network; };
 
            virtual std::shared_ptr<Wallet> wallet() noexcept;
 
            // Explicitly delete copy operations
            Seed(const Seed&) = delete;
            Seed& operator=(const Seed&) = delete;
            // Allow move operations
            Seed(Seed&&) noexcept = default;
            Seed& operator=(Seed&&) noexcept = default;
 
            static std::vector<uint16_t> mergeValues(
                const std::vector<uint16_t>& values1,
                const std::vector<uint16_t>& values2
                );
 
            static std::vector<uint16_t> mergeValues(const std::vector<std::vector<uint16_t>>& values);
 
            static std::vector<uint16_t> mergeAndZeorizeValues(
                std::vector<uint16_t>& values1,
                std::vector<uint16_t>& values2,
                bool del = true
                );
 
            static std::vector<uint16_t> mergeAndZeorizeValues(
                std::vector<std::vector<uint16_t>>& values,
                bool del = true
                );
 
            static std::vector<uint16_t> mergeWithPassword(
                const std::string& password,
                const std::vector<uint16_t>& values
                );
 
            static std::vector<uint16_t> mergeWithPasswordAndZeorize(
                    std::string& password,
                    std::vector<uint16_t>& values,
                    bool del = true
                    );
 
            static std::vector<uint16_t> mergeWithPassword(
                    const WipeableString& password,
                    const std::vector<uint16_t>& values
                    );
 
            static std::vector<uint16_t> mergeWithPasswordAndZeorize(
                    const WipeableString& password,
                    std::vector<uint16_t>& values,
                    bool del = true
                    );
        protected:
            Seed();
            std::unique_ptr<Address> m_address;
            std::shared_ptr<Wallet> m_wallet;
            uint64_t m_timestamp = 0;
            uint64_t m_height = 0;
            std::unique_ptr<KeyStore, KeyStoreDeleter> m_key;
            Network m_network;
    };
 
    class LegacySeed: public Seed {
        public:
            const WipeableString phrase(const SeedLanguage& language, const std::string& password = "") const override;
 
            const SeedIndices indices(const std::string& password = "") const override;
 
            static LegacySeed decode(
                    const std::string& phrase,
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    Network network = Network::MAIN
                    );
 
            static LegacySeed decode(
                    const SeedIndices& indices,
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    Network network = Network::MAIN
                    );
 
            static LegacySeed decode(
                    const std::vector<uint16_t>& values, 
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    Network network = Network::MAIN
                    );
 
            protected:
                explicit LegacySeed();
                std::unique_ptr<KeyStore, KeyStoreDeleter> m_seed;
    };
 
    class MoneroSeed: public Seed {
        public:
            const WipeableString phrase(const SeedLanguage& language, const std::string& passphrase = "") const override;
 
            const SeedIndices indices(const std::string& passphrase = "") const override;
 
            static MoneroSeed decode(
                    const std::string& phrase,
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    Network network = Network::MAIN,
                    const std::string& passphrase = ""
                    );
 
            static MoneroSeed decode(
                    const SeedIndices& indices,
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    Network network = Network::MAIN,
                    const std::string& passphrase = ""
                    );
 
            static MoneroSeed decode(
                    const std::vector<uint16_t>& values, 
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    Network network = Network::MAIN,
                    const std::string& password = ""
                    );
 
            static MoneroSeed create(
                    const std::array<unsigned char, 32>& random,
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    const Network network = Network::MAIN
                    );
 
            static MoneroSeed generate(
                    uint64_t height = 0,
                    uint64_t time = 0, 
                    const Network network = Network::MAIN
                    );
        protected:
            MoneroSeed() = default;
    };
 
    class Polyseed: public Seed {
        public:
            const WipeableString phrase(const SeedLanguage& language, const std::string& password = "") const override;
            const SeedIndices indices(const std::string& password = "") const override;
 
            MoneroSeed moneroSeed() const;
 
            static Polyseed create(
                    const std::array<unsigned char, 19>& random,
                    Network network = Network::MAIN,
                    uint64_t time = 0,
                    const std::string& passphrase = ""
                    );
 
            static Polyseed create(
                    const std::array<unsigned char, 32>& random,
                    Network network = Network::MAIN,
                    uint64_t time = 0,
                    const std::string& passphrase = ""
                    );
 
            static Polyseed generate(
                    Network network = Network::MAIN,
                    uint64_t time = 0,
                    const std::string& passphrase = ""
                    );
 
            static Polyseed decode(
                    const std::string& phrase, 
                    const Network network = Network::MAIN,
                    const std::string& password = "",
                    const std::string& passphrase = ""
                    );
 
            static Polyseed decode(
                    const std::string& phrase, 
                    const SeedLanguage& language, 
                    const Network network = Network::MAIN,
                    const std::string& password = "",
                    const std::string& passphrase = ""
                    );
 
            static Polyseed decode(
                    const SeedIndices& indices,
                    const Network network = Network::MAIN,
                    const std::string& password = "",
                    const std::string& passphrase = ""
                    );
 
            static Polyseed decode(
                    const std::vector<uint16_t>& values, 
                    const Network network = Network::MAIN,
                    const std::string& password = "",
                    const std::string& passphrase = ""
                    );
        protected:
            Polyseed();
            std::unique_ptr<PolyseedKeyStore, PolyseedKeyStoreDeleter> m_seed;
    };
 
    class Address {
        public:
            explicit Address(const std::string& address);
 
            [[nodiscard]] const Network network() const noexcept;
 
            [[nodiscard]] const AddressType type() const noexcept;
 
            virtual const std::string& fingerprint() const noexcept;
 
            bool isIntegrated() const noexcept;
 
            std::string paymentID() const noexcept;
 
            Address integratedAddress() const;
 
            [[nodiscard]] const size_t length() const noexcept;
 
            explicit operator std::string() const noexcept;
 
            operator const std::string&() const noexcept;
 
            operator const uint8_t*() const noexcept;
 
            bool operator==(const Address& other) const noexcept;
 
            bool operator==(const std::string& other) const noexcept;
 
            [[nodiscard]] static bool isValid(const std::string& address, const Network network = Network::MAIN) noexcept;
 
            [[nodiscard]] static Network network(const std::string& address);
 
            [[nodiscard]] static AddressType type(const std::string& address);
 
            [[nodiscard]] static std::string fingerprint(const std::string& address);
 
            [[nodiscard]] static bool isIntegrated(const std::string& address);
 
            [[nodiscard]] static std::string paymentID(const std::string& address, Network network = Network::MAIN);
 
            [[nodiscard]] static std::string integratedAddress(const std::string& address, Network network = Network::MAIN);
 
        protected:
            explicit Address(const std::string& address, Network network);
            static Address validAddress(const std::string& address);
            std::string m_address;
            Network m_network;
            AddressType m_type;
            mutable std::string m_fingerprint;
    };
 
    class OTS {
        public:
            explicit OTS();
 
            static const std::string version() noexcept;
 
            static std::array<int, 3> versionComponents() noexcept;
 
            static uint64_t heightFromTimestamp(uint64_t timestamp, Network network = Network::MAIN);
 
            static uint64_t timestampFromHeight(uint64_t height, Network network = Network::MAIN);
 
            static std::array<unsigned char, 32> random();
 
            static void random(size_t size, uint8_t *bytes);
 
            static bool lowEntropy(size_t size, const uint8_t* data, double minEntropy = 3.5) noexcept;
 
            static void enforceEntropy(bool enforce = true) noexcept;
 
            static void setMaxAccountDepth(uint32_t depth) noexcept;
 
            static void setMaxIndexDepth(uint32_t depth) noexcept;
 
            static void setMaxDepth(uint32_t account, uint32_t index) noexcept;
 
            static void resetMaxDepth() noexcept;
 
            static uint32_t maxAccountDepth(uint32_t depth = 0) noexcept;
 
            static uint32_t maxIndexDepth(uint32_t depth = 0) noexcept;
 
            static bool verifyData(
                    const std::string& data, 
                    const std::string& address, 
                    const std::string& signature,
                    bool legacyFallback = false
                    );
 
        protected:
            static void ensureEntropy(size_t size, const uint8_t* data, double minEntropy = 3.5);
 
        private:
            static bool sEnforceEntropy;
            static uint32_t sMaxAccountDepth;
            static uint32_t sMaxIndexDepth;
    };
 
    class SeedJar {
        public:
            seed_handle_t store(const Seed& seed) const noexcept;
            
            const Seed& get(seed_handle_t handle) const;
 
            const Seed& get(const std::string& fingerprint) const;
            uint32_t count() const noexcept;
            bool has(seed_handle_t handle) const noexcept;
            bool has(const std::string& fingerprint) const;
            std::vector<std::reference_wrapper<const Seed>> list() const noexcept;
            static const SeedJar& instance() noexcept;
    };
 
    class Wallet {
        public:
 
            uint64_t height() const noexcept { return m_height; };
 
            Address address(uint32_t account = 0, uint32_t index = 0) const noexcept;
 
            std::vector<Address> accounts(uint32_t max = 10, uint32_t offset = 0) const noexcept;
 
            std::vector<Address> subAddresses(uint32_t account = 0, uint32_t max = 10, uint32_t offset = 0) const noexcept;
 
            bool hasAddress(const std::string& address, uint32_t maxAccountDepth = 0, uint32_t maxIndexDepth = 0) const noexcept;
 
            bool hasAddress(const Address& address, uint32_t maxAccountDepth = 0, uint32_t maxIndexDepth = 0) const noexcept;
 
            std::pair<uint32_t, uint32_t> addressIndex(const std::string& address, uint32_t maxAccountDepth = 0, uint32_t maxIndexDepth = 0) const;
 
            std::pair<uint32_t, uint32_t> addressIndex(const Address& address, uint32_t maxAccountDepth = 0, uint32_t maxIndexDepth = 0) const;
 
            WipeableString secretViewKey() const noexcept;
 
            WipeableString publicViewKey() const noexcept;
 
            WipeableString secretSpendKey() const noexcept;
 
            WipeableString publicSpendKey() const noexcept;
 
            uint64_t importOutputs(const std::string& outputs);
 
            WipeableString exportKeyImages() const;
 
            TxDescription describeTransaction(const std::string& unsignedTransaction) const;
 
            std::vector<TxWarning> checkTransaction(const std::string& unsignedTransaction) const;
 
            std::vector<TxWarning> checkTransaction(const TxDescription& description) const noexcept;
 
            std::string signTransaction(const std::string& unsignedTransaction) const;
 
            std::string signData(const std::string& data) const noexcept;
 
            std::string signData(const std::string& data, const std::pair<uint32_t, uint32_t>& index) const;
 
            std::string signData(const std::string& data, const Address& address) const;
 
            std::string signData(const std::string& data, const std::string& address) const;
 
            static bool verifyData(
                    const std::string& data, 
                    const std::string& address, 
                    const std::string& signature,
                    bool legacyFallback = false
                    );
 
            static bool verifyData(
                    const std::string& data, 
                    const Address& address, 
                    const std::string& signature,
                    bool legacyFallback = false
                    );
 
            bool verifyData(
                    const std::string& data, 
                    const std::pair<uint32_t, uint32_t>& index,
                    const std::string& signature,
                    bool legacyFallback = false
                    ) const;
 
            bool verifyData(
                    const std::string& data, 
                    const std::string& signature,
                    bool legacyFallback = false
                    ) const;
 
            Wallet(const std::array<unsigned char, 32>& key, uint64_t height, const Network network) noexcept;
 
            Wallet(const KeyStore& key, uint64_t height, const Network network) noexcept;
 
            Wallet(const Account& account, const KeyStore& key, uint64_t height, const Network network) noexcept;
 
        protected:
            std::unique_ptr<KeyStore, KeyStoreDeleter> m_key;
            std::unique_ptr<Account, AccountDeleter> m_account;
            Network m_network;
            uint64_t m_height = 0;
    };
 
    class TxDescription {};
 
    class TxWarning {};
 
    // set this on the end because there will be a lot of bloat in the documentation.
    class WipeableString {
 
        public:
            WipeableString() noexcept = default;
 
            inline explicit WipeableString(const std::string& s): m_str(s) {};
 
            explicit WipeableString(const char* s);
 
            WipeableString(const char* s, size_t n);
 
            WipeableString(const WipeableString& other);
            
            WipeableString(WipeableString&& other) noexcept;
            
            WipeableString& operator=(const WipeableString& other);
            
            WipeableString& operator=(WipeableString&& other) noexcept;
 
            WipeableString& operator=(const char* s);
 
            ~WipeableString();
 
            std::string insecure() const noexcept;
 
            const char* c_str() const noexcept;
 
            const char* data() const noexcept;
 
            size_t size() const noexcept;
 
            bool empty() const noexcept;
 
            void clear() noexcept;
 
            size_t capacity() const noexcept;
 
            void reserve(size_t n);
 
            WipeableString substr(size_t pos = 0, size_t len = std::string::npos) const;
 
            size_t find(const WipeableString& str, size_t pos = 0) const noexcept;
            
            size_t find(const char* s, size_t pos = 0) const noexcept;
 
            WipeableString& append(const WipeableString& str);
 
            WipeableString& append(const char* s);
 
            WipeableString& operator+=(const WipeableString& str);
 
            WipeableString& operator+=(const char* s);
 
            bool operator==(const WipeableString& other) const noexcept;
 
            bool operator!=(const WipeableString& other) const noexcept;
 
            operator std::string() const;
 
            int compare(const WipeableString& other) const noexcept;
 
            friend std::ostream& operator<<(std::ostream& os, const WipeableString& str);
 
            static constexpr size_t npos = std::string::npos;
 
        private:
            std::string m_str;
 
            void wipe() noexcept;
    };
 
    class SeedIndices {
        public:
            SeedIndices() noexcept = default;
 
            inline explicit SeedIndices(const std::vector<uint16_t>& v): m_vec(v) {};
 
            explicit SeedIndices(size_t size): m_vec(size) {};
 
            SeedIndices(size_t size, uint16_t value): m_vec(size, value) {};
 
            SeedIndices(const SeedIndices& other): m_vec(other.m_vec) {};
 
            SeedIndices(SeedIndices&& other) noexcept: m_vec(std::move(other.m_vec)) {};
 
            SeedIndices& operator=(const SeedIndices& other);
 
            SeedIndices& operator=(SeedIndices&& other) noexcept;
 
            operator const uint8_t*() const noexcept;
 
            operator const char*() const noexcept;
 
            operator const std::vector<uint16_t>&() const noexcept;
 
            operator const std::string() const noexcept;
 
            bool operator==(const SeedIndices& other) const noexcept;
 
            bool operator==(const std::vector<uint16_t>& other) const noexcept;
 
            bool operator!=(const SeedIndices& other) const noexcept;
 
            bool operator!=(const std::vector<uint16_t>& other) const noexcept;
 
            const std::string numeric(const std::string& separator = "") const noexcept;
 
            const std::string hex(const std::string& separator = "") const noexcept;
 
            ~SeedIndices();
 
            size_t size() const noexcept;
 
            bool empty() const noexcept;
 
            void clear() noexcept;
 
            inline void reserve(size_t n) { m_vec.reserve(n); };
 
            inline void shrink_to_fit() { m_vec.shrink_to_fit(); };
 
            uint16_t& operator[](size_t pos);
            const uint16_t& operator[](size_t pos) const;
            uint16_t& at(size_t pos);
            const uint16_t& at(size_t pos) const;
 
            void push_back(uint16_t value);
 
            uint16_t emplace_back(uint16_t value);
 
            auto begin() noexcept { return m_vec.begin(); }
 
            auto end() noexcept { return m_vec.end(); }
 
            auto begin() const noexcept { return m_vec.begin(); }
 
            auto end() const noexcept { return m_vec.end(); }
 
            auto cbegin() const noexcept { return m_vec.cbegin(); }
 
            auto cend() const noexcept { return m_vec.cend(); }
 
            static SeedIndices fromNumeric(const std::string& numeric, const std::string& separator = "");
 
            static SeedIndices fromHex(const std::string& hex, const std::string& separator = "");
        private:
            std::vector<uint16_t> m_vec;
 
            void wipe() noexcept;
    };
} // namespace ots