Developer SDK

C# examples

Install the SDK · View source on GitHub ↗

provider/Status.cs

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 SDK hands the status
// values over as C ABI JSON with the Go field names; the readers and rules
// here are pure managed code that never throws on bad input, so SDK callbacks
// can use them and the self-test checks them without the native SDK runtime,
// a network or credentials.
using System.Globalization;
using System.Text.Json;

/// The status rules and the texts they produce.
internal static class StatusRules {
  /// 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. The line breaks are LF on every OS, as the contract's
  /// hash requires, also when git checks this file out with CRLF.
  public static readonly string ConsentDisclaimer = """
      Consent disclaimer: an app that integrates a URnetwork provider must collect the user's consent before it provides.
      Providing shares the user's internet connection: other URnetwork users' traffic exits through the user's device and IP address.
      This example starts providing without asking, because the consent screen belongs to your app.
      """.ReplaceLineEndings("\n");

  public const string StateStopped = "stopped";
  // the platform disconnected this client for its network's client limit, and
  // the SDK holds off reconnecting until the retry time
  public const string StateClientLimit = "client limit";
  public const string StateStarting = "starting";
  public const string StatePaused = "paused";
  public const string StateProviding = "providing";

  // the payout wallet before the first wallet read finishes
  public const string PayoutWalletChecking = "checking";
  // the payout wallet when the first wallet read failed
  public const string PayoutWalletUnavailable = "unavailable";
  // the payout wallet when no wallet is mapped
  public const string PayoutWalletNotSet = "not set";

  public const string PayoutWalletScopeHotkey = "hotkey";
  public const string PayoutWalletScopeProvider = "this provider";
  public const string PayoutWalletScopeNetwork = "network";
  public const string PayoutWalletScopeAnotherProvider = "another provider";

  // C ABI values (urnetwork_sdk.h): URNET_PROVIDE_MODE_*
  public const long ProvideModeNone = 0;
  public const long ProvideModeNetwork = 1;
  public const long ProvideModePublic = 3;
  // URNET_CLIENT_LIMIT_STATUS_*
  public const string ClientLimitStatusNone = "";
  public const string ClientLimitStatusExceeded = "client_limit_exceeded";
  // the consent_scope of a GET /sn/wallet entry
  public const string SnWalletConsentScopeProvider = "provider";
  public const string SnWalletConsentScopeNetwork = "network";
  // a network's hotkey delegation entry; it comes with a later server and SDK
  // change, and the app only labels it
  public const string SnWalletConsentScopeHotkey = "hotkey";

  // Distinct clients are counted up to this many; beyond it the count is a
  // lower bound, shown with a trailing "+".
  public const int ClientsServedLimit = 100 * 1000;

  /// 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, decided with
  /// midpoints away from zero as the Go reference's math.Round does. The text
  /// rounds ties to even, as Go's %.1f does (1280 bytes is "1.2 KiB").
  public static string FormatByteCount(long byteCount) {
    if (byteCount < 1024) {
      return byteCount.ToString(CultureInfo.InvariantCulture) + " B";
    }
    string[] units = ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB"];
    double value = byteCount / 1024.0;
    int unitIndex = 0;
    while (unitIndex < units.Length - 1 &&
           1024 <= Math.Round(value * 10, MidpointRounding.AwayFromZero) / 10) {
      value /= 1024;
      unitIndex += 1;
    }
    return value.ToString("F1", CultureInfo.InvariantCulture) + " " +
           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, or one
  /// after the year 9999, shows "client limit".
  public static string StatusText(string state, long clientLimitRetryTime) {
    if (state != StateClientLimit || clientLimitRetryTime <= 0) {
      return state;
    }
    const long minuteMillis = 60 * 1000;
    long retryMinute = clientLimitRetryTime / minuteMillis +
                       (clientLimitRetryTime % minuteMillis == 0 ? 0 : 1);
    if (DateTimeOffset.MaxValue.ToUnixTimeSeconds() / 60 < retryMinute) {
      return state;
    }
    var retryTime = DateTimeOffset.FromUnixTimeSeconds(retryMinute * 60);
    return $"{StateClientLimit}, retry at {retryTime.ToString("HH:mm", CultureInfo.InvariantCulture)} UTC";
  }

  /// 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.
  public static string ProviderState(long provideMode, string clientLimitStatus,
                                     bool providePaused, bool provideEnabled,
                                     bool providerConnected) {
    if (provideMode != ProvideModePublic) {
      return StateStopped;
    }
    if (clientLimitStatus == ClientLimitStatusExceeded) {
      return StateClientLimit;
    }
    if (providePaused) {
      return StatePaused;
    }
    if (provideEnabled && providerConnected) {
      return StateProviding;
    }
    return StateStarting;
  }

  /// 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.
  public static string PayoutWalletScope(string walletConsentScope,
                                         string walletClientId,
                                         string clientId) {
    if (walletConsentScope == SnWalletConsentScopeHotkey) {
      return PayoutWalletScopeHotkey;
    }
    if (walletClientId == "") {
      return PayoutWalletScopeNetwork;
    }
    if (walletClientId == clientId) {
      return PayoutWalletScopeProvider;
    }
    return PayoutWalletScopeAnotherProvider;
  }

  /// The peer of one provider contract, from the contract details JSON of the
  /// provider contract listeners, 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; "" when there is none.
  public static string ContractPeerKey(string? contractDetailsJson,
                                       bool receive) {
    if (ParseObject(contractDetailsJson) is not { } details) {
      return "";
    }
    if (details.TryGetProperty("ContractTransferPath", out var path) &&
        path.ValueKind == JsonValueKind.Object) {
      if (PresentId(path, receive ? "SourceId" : "DestinationId") is { } peerId) {
        return peerId;
      }
      if (PresentId(path, "StreamId") is { } streamId) {
        return "stream:" + streamId;
      }
    }
    if (PresentId(details, "ContractId") is { } contractId) {
      return "contract:" + contractId;
    }
    return "";
  }

  /// The client limit status of urnet_device_get_client_limit_status. NULL,
  /// which the call returns only when it cannot run, reads as no limit.
  public static (string Status, long RetryTime) ParseClientLimitStatus(
      string? clientLimitStatusJson) {
    if (ParseObject(clientLimitStatusJson) is not { } status) {
      return (Status: ClientLimitStatusNone, RetryTime: 0);
    }
    return (Status: StringProperty(status, "Status"),
            RetryTime: Int64Property(status, "RetryTime"));
  }

  /// Bytes relayed for clients, in both directions, since the device started,
  /// from urnet_device_get_provider_packet_stats; 0 when the stats are NULL.
  public static long DataProvidedByteCount(string? providerPacketStatsJson) {
    if (ParseObject(providerPacketStatsJson) is not { } packetStats) {
      return 0;
    }
    return Int64Property(packetStats, "RemoteEgressByteCount") +
           Int64Property(packetStats, "RemoteIngressByteCount");
  }

  /// Whether a wallet read succeeded, from the arguments of its
  /// urnet_sn_get_wallet_cb: no error text, and a result without an error.
  public static bool WalletReadSucceeded(string? resultJson, string? errorText) {
    if (errorText != null || ParseObject(resultJson) is not { } result) {
      return false;
    }
    return !result.TryGetProperty("error", out var resultError) ||
           resultError.ValueKind == JsonValueKind.Null;
  }

  /// The payout wallet text and scope of the effective wallet that the SDK
  /// caches (urnet_device_local_get_sn_wallet): the coldkey address with its
  /// scope, or "not set" without a mapped coldkey.
  public static (string PayoutWallet, string PayoutWalletScope)
      ParsePayoutWallet(string? walletJson, string clientId) {
    if (ParseObject(walletJson) is not { } wallet ||
        StringProperty(wallet, "coldkey_ss58") is not { Length: > 0 } coldkeySs58) {
      return (PayoutWallet: PayoutWalletNotSet, PayoutWalletScope: "");
    }
    string scope = PayoutWalletScope(StringProperty(wallet, "consent_scope"),
                                     StringProperty(wallet, "client_id"), clientId);
    return (PayoutWallet: coldkeySs58, PayoutWalletScope: scope);
  }

  /// The root object of a C ABI JSON value; null for NULL, JSON null, another
  /// kind of value, or text that does not parse.
  private static JsonElement? ParseObject(string? json) {
    if (json == null) {
      return null;
    }
    try {
      using var document = JsonDocument.Parse(json);
      if (document.RootElement.ValueKind != JsonValueKind.Object) {
        return null;
      }
      return document.RootElement.Clone();
    } catch (Exception e) when (e is JsonException or ArgumentException) {
      return null;
    }
  }

  /// A string property, or "" when it is missing or not a string.
  private static string StringProperty(JsonElement element, string name) {
    if (element.TryGetProperty(name, out var value) &&
        value.ValueKind == JsonValueKind.String) {
      return value.GetString() ?? "";
    }
    return "";
  }

  /// An integer property, or 0 when it is missing or not an integer.
  private static long Int64Property(JsonElement element, string name) {
    if (element.TryGetProperty(name, out var value) &&
        value.ValueKind == JsonValueKind.Number &&
        value.TryGetInt64(out long number)) {
      return number;
    }
    return 0;
  }

  /// An id property in canonical form, or null when it is missing, not a
  /// UUID or all zeros.
  private static string? PresentId(JsonElement element, string name) {
    string? id = Uuid.Parse(StringProperty(element, name));
    return id == Uuid.Zero ? null : id;
  }
}

/// One status snapshot.
internal sealed record ProviderStatus {
  public required string State { get; init; }
  // the end of the client limit hold in unix milliseconds, shown with the
  // client limit state; 0 when unknown
  public long ClientLimitRetryTime { get; init; }
  public int ClientsServed { get; init; }
  public bool ClientsServedAtLimit { get; init; }
  public long DataProvidedByteCount { get; init; }
  // a coldkey ss58 address, or StatusRules.PayoutWalletChecking,
  // PayoutWalletUnavailable or PayoutWalletNotSet
  public required string PayoutWallet { get; init; }
  // "" unless PayoutWallet is an address
  public string PayoutWalletScope { get; init; } = "";

  /// The status line, for example
  /// "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: 5Grw... (network)".
  public override string ToString() {
    string clientsServed = ClientsServed.ToString(CultureInfo.InvariantCulture) +
                           (ClientsServedAtLimit ? "+" : "");
    string payoutWallet = PayoutWalletScope == ""
                              ? PayoutWallet
                              : $"{PayoutWallet} ({PayoutWalletScope})";
    return $"status: {StatusRules.StatusText(State, ClientLimitRetryTime)} | clients served: {clientsServed} | data provided: {StatusRules.FormatByteCount(DataProvidedByteCount)} | payout wallet: {payoutWallet}";
  }

  /// 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.
  public StatusKey Key() {
    return new StatusKey(
        StatusText: StatusRules.StatusText(State, ClientLimitRetryTime),
        ClientsServed: ClientsServed,
        ClientsServedAtLimit: ClientsServedAtLimit,
        PayoutWallet: PayoutWallet,
        PayoutWalletScope: PayoutWalletScope);
  }
}

/// The parts of a status snapshot whose change prints a status line.
internal readonly record struct StatusKey(string StatusText, int ClientsServed,
                                          bool ClientsServedAtLimit,
                                          string PayoutWallet,
                                          string PayoutWalletScope);

/// 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.
internal sealed class ServedClients {
  private readonly int limit;
  private readonly object stateLock = new();
  // the ContractPeerKey values counted so far
  private readonly HashSet<string> peerKeys = [];
  private bool atLimit;

  /// An empty count that keeps at most limit distinct peers.
  public ServedClients(int limit) {
    this.limit = limit;
  }

  /// Counts the peer of one provider contract, from its contract details JSON.
  public void Add(string? contractDetailsJson, bool receive) {
    string peerKey = StatusRules.ContractPeerKey(contractDetailsJson, receive);
    if (peerKey == "") {
      return;
    }
    lock (stateLock) {
      if (peerKeys.Contains(peerKey)) {
        return;
      }
      if (limit <= peerKeys.Count) {
        atLimit = true;
        return;
      }
      peerKeys.Add(peerKey);
    }
  }

  /// The distinct count, and whether the count stopped at the limit.
  public (int Count, bool AtLimit) Count() {
    lock (stateLock) {
      return (Count: peerKeys.Count, AtLimit: atLimit);
    }
  }
}