Developer SDK

C++ examples

Install the SDK · View source on GitHub ↗

provider/status.hpp

c++
// The provider status that every provider example shows, with the exact text
// rules of PROVIDER_CONTRACT.md ("Status"): providing state, clients served,
// data provided and the payout wallet, read only. The functions are pure and
// take the C++ SDK's data types (urnetwork_sdk.hpp), which need no sdk calls,
// so the self-test checks them without the sdk library, a network or
// credentials.
#pragma once

#include <cstddef>
#include <cstdint>
#include <cstdio>
#include <iostream>
#include <mutex>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_set>
#include <utility>

#include <urnetwork_sdk.hpp>

namespace provider {

// Shown once at start, and in every example's README. The app that integrates
// a provider owns the consent screen; this example starts without asking. One
// literal per line with explicit line breaks, so the text stays exact in a
// checkout with CRLF line endings.
inline constexpr std::string_view consentDisclaimer =
    "Consent disclaimer: an app that integrates a URnetwork provider must collect the user's consent before it provides.\n"
    "Providing shares the user's internet connection: other URnetwork users' traffic exits through the user's device and IP address.\n"
    "This example starts providing without asking, because the consent screen belongs to your app.";

inline constexpr std::string_view providerStateStopped = "stopped";
// the platform disconnected this client for its network's client limit, and
// the sdk holds off reconnecting until the retry time
inline constexpr std::string_view providerStateClientLimit = "client limit";
inline constexpr std::string_view providerStateStarting = "starting";
inline constexpr std::string_view providerStatePaused = "paused";
inline constexpr std::string_view providerStateProviding = "providing";

// the payout wallet before the first wallet read finishes
inline constexpr std::string_view payoutWalletChecking = "checking";
// the payout wallet when the first wallet read failed
inline constexpr std::string_view payoutWalletUnavailable = "unavailable";
// the payout wallet when no wallet is mapped
inline constexpr std::string_view payoutWalletNotSet = "not set";

inline constexpr std::string_view payoutWalletScopeHotkey = "hotkey";
inline constexpr std::string_view payoutWalletScopeProvider = "this provider";
inline constexpr std::string_view payoutWalletScopeNetwork = "network";
inline constexpr std::string_view payoutWalletScopeAnotherProvider = "another provider";

// The consent_scope of a network's hotkey delegation entry in GET /sn/wallet.
// Hotkey delegations come with a later server and sdk change, which adds the
// sdk's own constant; the app only labels the entry.
inline constexpr std::string_view snWalletConsentScopeHotkey = "hotkey";

// Distinct clients are counted up to this many; beyond it the count is a lower
// bound, shown with a trailing "+".
inline constexpr std::size_t clientsServedLimit = 100 * 1000;

// the nil id, which marks an absent peer in a contract path
inline constexpr std::string_view zeroIdString = "00000000-0000-0000-0000-000000000000";

// Prints one line on stdout at once, also when stdout is a file or a pipe
// (launchd and the Windows task keep the console output in files).
inline void printLine(std::string_view line) {
    std::cout << line << std::endl;
}

// Binary units with one decimal: "0 B", "1023 B", "1.0 KiB", "12.4 MiB". A
// value that rounds to 1024.0 moves to the next unit. The arithmetic is exact
// integer arithmetic, so the text does not depend on the C++ library's float
// formatting; a tie rounds to even, as Go's %.1f does.
inline std::string formatByteCount(int64_t byteCount) {
    static const char* const units[] = {"KiB", "MiB", "GiB", "TiB", "PiB", "EiB"};
    if (byteCount < 1024) {
        return std::to_string(byteCount) + " B";
    }
    auto count = static_cast<uint64_t>(byteCount);
    uint64_t divisor = 1024;
    std::size_t unitIndex = 0;
    while (unitIndex + 1 < std::size(units)) {
        // the value rounds to 1024.0 or more from 1023.95 up
        uint64_t whole = count / divisor;
        uint64_t remainder = count % divisor;
        if (whole < 1023 || (whole == 1023 && 20 * remainder < 19 * divisor)) {
            break;
        }
        divisor *= 1024;
        unitIndex += 1;
    }
    uint64_t scaled = count % divisor * 10;
    uint64_t tenths = count / divisor * 10 + scaled / divisor;
    uint64_t remainder = scaled % divisor;
    if (divisor < 2 * remainder || (divisor == 2 * remainder && tenths % 2 == 1)) {
        tenths += 1;
    }
    return std::to_string(tenths / 10) + "." + std::to_string(tenths % 10) + " " + units[unitIndex];
}

// The status field text: the state, and for the client limit state the time
// the sdk retries, for example "client limit, retry at 19:05 UTC". The retry
// time (unix milliseconds) is rounded up to the next whole minute in UTC, so
// the shown time is never before the real retry; a retry time of 0 shows
// "client limit". Unix time has no leap seconds, so every day is 1440
// minutes.
inline std::string providerStatusText(std::string_view state, int64_t clientLimitRetryTime) {
    if (state != providerStateClientLimit || clientLimitRetryTime <= 0) {
        return std::string(state);
    }
    const int64_t minuteMillis = 60 * 1000;
    int64_t retryMinute = clientLimitRetryTime / minuteMillis + (clientLimitRetryTime % minuteMillis != 0 ? 1 : 0);
    int minuteOfDay = static_cast<int>(retryMinute % (24 * 60));
    char clock[8];
    std::snprintf(clock, sizeof(clock), "%02d:%02d", minuteOfDay / 60, minuteOfDay % 60);
    return std::string(providerStateClientLimit) + ", retry at " + clock + " UTC";
}

// One status snapshot.
struct ProviderStatus {
    std::string state;
    // the end of the client limit hold in unix milliseconds, shown with the
    // client limit state; 0 when unknown
    int64_t clientLimitRetryTime = 0;
    std::size_t clientsServed = 0;
    bool clientsServedAtLimit = false;
    int64_t dataProvidedByteCount = 0;
    // a coldkey ss58 address, or payoutWalletChecking, payoutWalletUnavailable,
    // payoutWalletNotSet
    std::string payoutWallet;
    // empty unless payoutWallet is an address
    std::string payoutWalletScope;

    // The status line, for example "status: providing | clients served: 3 |
    // data provided: 12.4 MiB | payout wallet: 5Grw... (network)".
    std::string line() const {
        std::string payoutWalletText = payoutWallet;
        if (!payoutWalletScope.empty()) {
            payoutWalletText += " (" + payoutWalletScope + ")";
        }
        return "status: " + providerStatusText(state, clientLimitRetryTime) +
            " | clients served: " + std::to_string(clientsServed) + (clientsServedAtLimit ? "+" : "") +
            " | data provided: " + formatByteCount(dataProvidedByteCount) +
            " | payout wallet: " + payoutWalletText;
    }

    // The fields that change rarely. A change prints a status line at once;
    // the data counter alone only prints on the periodic line. The status text
    // carries the client limit retry time, so a new retry time prints too.
    std::string key() const {
        return providerStatusText(state, clientLimitRetryTime) + "|" + std::to_string(clientsServed) + "|" +
            (clientsServedAtLimit ? "true" : "false") + "|" + payoutWallet + "|" + payoutWalletScope;
    }
};

// The providing state from the device getters, in this order: stopped unless
// the provide mode is public; client limit while the sdk holds this client off
// for its network's client limit; paused while paused; providing once the
// provider is enabled and its platform carrier is connected; starting
// otherwise.
inline std::string_view providerState(
    int64_t provideMode, std::string_view clientLimitStatus, bool providePaused, bool provideEnabled, bool providerConnected) {
    if (provideMode != urnet::ProvideModePublic) {
        return providerStateStopped;
    }
    if (clientLimitStatus == urnet::ClientLimitStatusExceeded) {
        return providerStateClientLimit;
    }
    if (providePaused) {
        return providerStatePaused;
    }
    if (provideEnabled && providerConnected) {
        return providerStateProviding;
    }
    return providerStateStarting;
}

// Which owner the effective payout wallet belongs to. The consent scope comes
// first: a hotkey delegation is network-level, with no client id, but is not
// the network's wallet. Otherwise by the wallet's client id: this provider's
// own mapping, the network's wallet, or another provider of the network.
inline std::string_view payoutWalletScope(
    std::string_view walletConsentScope, std::string_view walletClientId, std::string_view clientId) {
    if (walletConsentScope == snWalletConsentScopeHotkey) {
        return payoutWalletScopeHotkey;
    }
    if (walletClientId.empty()) {
        return payoutWalletScopeNetwork;
    }
    if (walletClientId == clientId) {
        return payoutWalletScopeProvider;
    }
    return payoutWalletScopeAnotherProvider;
}

// The payout wallet to show from the sdk's cached wallet: the coldkey and its
// scope label for this client, or payoutWalletNotSet with no scope when no
// wallet is mapped.
inline std::pair<std::string, std::string> payoutWalletDisplay(
    const std::optional<urnet::SnWallet>& wallet, std::string_view clientId) {
    if (!wallet || wallet->coldkey_ss58.empty()) {
        return {std::string(payoutWalletNotSet), ""};
    }
    auto scope = payoutWalletScope(
        wallet->consent_scope.value_or(""), wallet->client_id.value_or(""), clientId);
    return {wallet->coldkey_ss58, std::string(scope)};
}

// Whether a wallet read (GET /sn/wallet) succeeded: no error text, a result,
// and no error in the result.
inline bool walletReadSucceeded(
    const std::optional<urnet::SnGetWalletResult>& result, const std::optional<std::string>& error) {
    return !error && result && !result->error;
}

// Bytes relayed for clients, in both directions, since the device started; 0
// when the stats are null.
inline int64_t dataProvidedByteCount(const std::optional<urnet::PacketStats>& packetStats) {
    if (!packetStats) {
        return 0;
    }
    return packetStats->RemoteEgressByteCount + packetStats->RemoteIngressByteCount;
}

// The peer of one provider contract, by direction as the sdk's contract
// screens resolve it: the source of a receive (ingress) contract, the
// destination of a send (egress) contract. A path without that client id is
// keyed by its stream id, then by the contract id. Empty when the contract
// names no peer.
inline std::string contractPeerKey(const urnet::ContractDetails& details, bool receive) {
    auto present = [](const std::optional<std::string>& id) {
        return id && !id->empty() && *id != zeroIdString;
    };
    if (const auto& path = details.ContractTransferPath) {
        const auto& peerId = receive ? path->SourceId : path->DestinationId;
        if (present(peerId)) {
            return *peerId;
        }
        if (present(path->StreamId)) {
            return "stream:" + *path->StreamId;
        }
    }
    if (present(details.ContractId)) {
        return "contract:" + *details.ContractId;
    }
    return "";
}

// The distinct clients that held a contract with this provider since the app
// started. Safe for concurrent use: the sdk delivers contract details on its
// own threads.
class ClientsServed {
public:
    // An empty count that keeps at most limit distinct peers.
    explicit ClientsServed(std::size_t peerLimit) : limit(peerLimit) {}

    // Counts the peer of one provider contract.
    void add(const std::optional<urnet::ContractDetails>& details, bool receive) {
        if (!details) {
            return;
        }
        std::string peerKey = contractPeerKey(*details, receive);
        if (peerKey.empty()) {
            return;
        }
        std::lock_guard<std::mutex> lock(stateLock);
        if (peerKeys.count(peerKey)) {
            return;
        }
        if (limit <= peerKeys.size()) {
            atLimit = true;
            return;
        }
        peerKeys.insert(std::move(peerKey));
    }

    // The distinct count, and whether the count stopped at the limit.
    std::pair<std::size_t, bool> count() const {
        std::lock_guard<std::mutex> lock(stateLock);
        return {peerKeys.size(), atLimit};
    }

private:
    const std::size_t limit;
    mutable std::mutex stateLock;
    // contractPeerKey values
    std::unordered_set<std::string> peerKeys;
    bool atLimit = false;
};

}  // namespace provider