Developer SDK

Java examples

Install the SDK · View source on GitHub ↗

provider/ProviderStatus.java

java
// 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. It also reads the status
// values that the SDK's C ABI returns as JSON. Nothing here calls the SDK, so
// the self-test checks it without a network, credentials or the native SDK
// runtime.
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.HashSet;
import java.util.Locale;
import java.util.Map;
import java.util.Set;

/**
 * One status snapshot. payoutWallet is a coldkey ss58 address or one of the PAYOUT_WALLET texts;
 * payoutWalletScope is "" unless payoutWallet is an address. clientLimitRetryTime is the end of the
 * client limit hold in unix milliseconds, 0 when there is none.
 */
record ProviderStatus(String state, long clientLimitRetryTime,
                      int clientsServed, boolean clientsServedAtLimit,
                      long dataProvidedByteCount, String payoutWallet,
                      String payoutWalletScope) {
  // 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.
  static final String CONSENT_DISCLAIMER = """
      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.""";

  static final String STATE_STOPPED = "stopped";
  // the platform disconnected this client for its network's client limit,
  // and the sdk holds off reconnecting until the retry time
  static final String STATE_CLIENT_LIMIT = "client limit";
  static final String STATE_STARTING = "starting";
  static final String STATE_PAUSED = "paused";
  static final String STATE_PROVIDING = "providing";

  // the payout wallet before the first wallet read finishes
  static final String PAYOUT_WALLET_CHECKING = "checking";
  // the payout wallet when the first wallet read failed
  static final String PAYOUT_WALLET_UNAVAILABLE = "unavailable";
  // the payout wallet when no wallet is mapped
  static final String PAYOUT_WALLET_NOT_SET = "not set";

  static final String PAYOUT_WALLET_SCOPE_HOTKEY = "hotkey";
  static final String PAYOUT_WALLET_SCOPE_PROVIDER = "this provider";
  static final String PAYOUT_WALLET_SCOPE_NETWORK = "network";
  static final String PAYOUT_WALLET_SCOPE_ANOTHER_PROVIDER = "another provider";

  // the provide modes of the c abi (URNET_PROVIDE_MODE_*)
  static final long PROVIDE_MODE_NONE = 0;
  static final long PROVIDE_MODE_NETWORK = 1;
  static final long PROVIDE_MODE_PUBLIC = 3;

  // the client limit status values of the c abi (URNET_CLIENT_LIMIT_STATUS_*)
  static final String CLIENT_LIMIT_STATUS_NONE = "";
  static final String CLIENT_LIMIT_STATUS_EXCEEDED = "client_limit_exceeded";

  // the consent_scope values of GET /sn/wallet. Hotkey delegations come with
  // a later server and sdk change; the app only labels the entry.
  static final String SN_WALLET_CONSENT_SCOPE_HOTKEY = "hotkey";
  static final String SN_WALLET_CONSENT_SCOPE_NETWORK = "network";
  static final String SN_WALLET_CONSENT_SCOPE_PROVIDER = "provider";

  // distinct clients are counted up to this many; beyond it the count is a
  // lower bound, shown with a trailing "+"
  static final int CLIENTS_SERVED_LIMIT = 100 * 1000;

  // the client limit status when there is none, or when it cannot be read
  static final ClientLimit NO_CLIENT_LIMIT =
      new ClientLimit(CLIENT_LIMIT_STATUS_NONE, 0);

  private static final String ZERO_ID = "00000000-0000-0000-0000-000000000000";
  private static final String[] BYTE_UNITS = {"KiB", "MiB", "GiB",
                                               "TiB", "PiB", "EiB"};
  private static final long MINUTE_MILLIS = 60 * 1000;
  private static final long DAY_MINUTES = 24 * 60;

  /**
   * The status line, for example "status: providing | clients served: 3 | data provided: 12.4 MiB
   * | payout wallet: 5Grw... (network)".
   */
  String line() {
    String payoutWalletText = payoutWallet;
    if (!payoutWalletScope.isEmpty()) {
      payoutWalletText = payoutWallet + " (" + payoutWalletScope + ")";
    }
    return String.format(
        Locale.ROOT,
        "status: %s | clients served: %d%s | data provided: %s | payout wallet: %s",
        statusText(state, clientLimitRetryTime), clientsServed,
        clientsServedAtLimit ? "+" : "",
        formatByteCount(dataProvidedByteCount), 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.
   */
  String key() {
    return String.format(Locale.ROOT, "%s|%d|%b|%s|%s",
                         statusText(state, clientLimitRetryTime),
                         clientsServed, clientsServedAtLimit, payoutWallet,
                         payoutWalletScope);
  }

  /**
   * 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".
   */
  static String statusText(String state, long clientLimitRetryTime) {
    if (!STATE_CLIENT_LIMIT.equals(state) || clientLimitRetryTime <= 0) {
      return state;
    }
    // whole minutes since the epoch, rounded up without overflow
    long retryMinute = (clientLimitRetryTime - 1) / MINUTE_MILLIS + 1;
    long minuteOfDay = retryMinute % DAY_MINUTES;
    return String.format(Locale.ROOT, "%s, retry at %02d:%02d UTC",
                         STATE_CLIENT_LIMIT, minuteOfDay / 60,
                         minuteOfDay % 60);
  }

  /**
   * 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 tenth is the nearest one with ties to even, from the exact
   * binary value, as Go's %.1f rounds it: 1280 bytes (1.25 KiB) shows "1.2 KiB" and 1792 bytes
   * "1.8 KiB". String.format rounds ties up, so BigDecimal does the rounding. The unit check
   * follows the Go reference: double division, rounded half up.
   */
  static String formatByteCount(long byteCount) {
    if (byteCount < 1024) {
      return byteCount + " B";
    }
    double value = (double)byteCount / 1024;
    int unitIndex = 0;
    while (unitIndex < BYTE_UNITS.length - 1 &&
           1024 <= Math.round(value * 10) / 10.0) {
      value /= 1024;
      unitIndex += 1;
    }
    return new BigDecimal(value)
        .setScale(1, RoundingMode.HALF_EVEN)
        .toPlainString() +
        " " + BYTE_UNITS[unitIndex];
  }

  /**
   * 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.
   */
  static String providerState(long provideMode, String clientLimitStatus,
                              boolean providePaused, boolean provideEnabled,
                              boolean providerConnected) {
    if (provideMode != PROVIDE_MODE_PUBLIC) {
      return STATE_STOPPED;
    }
    if (CLIENT_LIMIT_STATUS_EXCEEDED.equals(clientLimitStatus)) {
      return STATE_CLIENT_LIMIT;
    }
    if (providePaused) {
      return STATE_PAUSED;
    }
    if (provideEnabled && providerConnected) {
      return STATE_PROVIDING;
    }
    return STATE_STARTING;
  }

  /**
   * 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.
   */
  static String payoutWalletScope(String walletConsentScope,
                                  String walletClientId, String clientId) {
    if (SN_WALLET_CONSENT_SCOPE_HOTKEY.equals(walletConsentScope)) {
      return PAYOUT_WALLET_SCOPE_HOTKEY;
    }
    if (walletClientId == null || walletClientId.isEmpty()) {
      return PAYOUT_WALLET_SCOPE_NETWORK;
    }
    if (walletClientId.equals(clientId)) {
      return PAYOUT_WALLET_SCOPE_PROVIDER;
    }
    return PAYOUT_WALLET_SCOPE_ANOTHER_PROVIDER;
  }

  /**
   * The peer of one provider contract, from the c abi's contract details JSON, 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 the details name none of them or do not parse.
   */
  static String contractPeerKey(String contractDetailsJson, boolean receive) {
    try {
      Map<String, Object> details = Json.parseNullableObject(contractDetailsJson);
      if (details == null) {
        return "";
      }
      Map<String, Object> path = Json.object(details, "ContractTransferPath");
      if (path != null) {
        String peerId =
            presentId(Json.string(path, receive ? "SourceId" : "DestinationId"));
        if (peerId != null) {
          return peerId;
        }
        String streamId = presentId(Json.string(path, "StreamId"));
        if (streamId != null) {
          return "stream:" + streamId;
        }
      }
      String contractId = presentId(Json.string(details, "ContractId"));
      if (contractId != null) {
        return "contract:" + contractId;
      }
      return "";
    } catch (Json.ParseException e) {
      // the sdk writes these details; a value that does not parse counts no peer
      return "";
    }
  }

  /** The canonical form of an id; null for a missing, malformed or all-zero id. */
  private static String presentId(String id) {
    if (id == null) {
      return null;
    }
    String canonicalId = InstallationState.parseId(id);
    if (canonicalId == null || ZERO_ID.equals(canonicalId)) {
      return null;
    }
    return canonicalId;
  }

  /**
   * One client limit readout: status is CLIENT_LIMIT_STATUS_NONE or CLIENT_LIMIT_STATUS_EXCEEDED,
   * retryTime the end of the hold in unix milliseconds, 0 when there is none.
   */
  record ClientLimit(String status, long retryTime) {}

  /**
   * The c abi's client limit status JSON, for example {"Status": "client_limit_exceeded",
   * "RetryTime": 1791313500000}. NULL (the call could not run) and a value that does not parse read
   * as no limit.
   */
  static ClientLimit parseClientLimit(String clientLimitStatusJson) {
    try {
      Map<String, Object> members = Json.parseNullableObject(clientLimitStatusJson);
      if (members == null) {
        return NO_CLIENT_LIMIT;
      }
      String status = Json.string(members, "Status");
      return new ClientLimit(status == null ? CLIENT_LIMIT_STATUS_NONE : status,
                             Json.longValue(members, "RetryTime", 0));
    } catch (Json.ParseException e) {
      return NO_CLIENT_LIMIT;
    }
  }

  /**
   * RemoteEgressByteCount + RemoteIngressByteCount of the c abi's provider packet stats JSON: bytes
   * relayed for clients in both directions since the device started; 0 when the stats are null.
   */
  static long dataProvidedByteCount(String packetStatsJson) {
    try {
      Map<String, Object> members = Json.parseNullableObject(packetStatsJson);
      if (members == null) {
        return 0;
      }
      return Json.longValue(members, "RemoteEgressByteCount", 0) +
          Json.longValue(members, "RemoteIngressByteCount", 0);
    } catch (Json.ParseException e) {
      return 0;
    }
  }

  /** The fields of an SnWallet that the app shows; "" for an absent field. */
  record SnWallet(String coldkeySs58, String clientId, String consentScope) {}

  /** The c abi's SnWallet JSON (urnet_device_local_get_sn_wallet); null for NULL or null. */
  static SnWallet parseSnWallet(String snWalletJson) throws Json.ParseException {
    Map<String, Object> members = Json.parseNullableObject(snWalletJson);
    if (members == null) {
      return null;
    }
    return new SnWallet(orEmpty(Json.string(members, "coldkey_ss58")),
                        orEmpty(Json.string(members, "client_id")),
                        orEmpty(Json.string(members, "consent_scope")));
  }

  /**
   * Whether a wallet read succeeded, from the two values of the c abi's wallet callback: no error,
   * and a result (an SnGetWalletResult JSON) without an error of its own.
   */
  static boolean walletReadSucceeded(String resultJson, String error) {
    if (error != null) {
      return false;
    }
    try {
      Map<String, Object> result = Json.parseNullableObject(resultJson);
      return result != null && Json.object(result, "error") == null;
    } catch (Json.ParseException e) {
      return false;
    }
  }

  /** The payout wallet field: an address with its scope, or one of the PAYOUT_WALLET texts with scope "". */
  record PayoutWallet(String wallet, String scope) {}

  /** The payout wallet before the first wallet read finishes. */
  static final PayoutWallet PAYOUT_WALLET_BEFORE_READ =
      new PayoutWallet(PAYOUT_WALLET_CHECKING, "");

  /**
   * The payout wallet after one wallet read: a failed first read shows unavailable and a later
   * failure keeps the last value; a read without a mapped wallet shows not set; otherwise the
   * effective wallet's coldkey with its scope for this client.
   */
  static PayoutWallet payoutWalletAfterRead(PayoutWallet current,
                                            boolean readSucceeded,
                                            SnWallet effectiveWallet,
                                            String clientId) {
    if (!readSucceeded) {
      if (PAYOUT_WALLET_CHECKING.equals(current.wallet())) {
        return new PayoutWallet(PAYOUT_WALLET_UNAVAILABLE, "");
      }
      return current;
    }
    if (effectiveWallet == null || effectiveWallet.coldkeySs58().isEmpty()) {
      return new PayoutWallet(PAYOUT_WALLET_NOT_SET, "");
    }
    return new PayoutWallet(
        effectiveWallet.coldkeySs58(),
        payoutWalletScope(effectiveWallet.consentScope(),
                          effectiveWallet.clientId(), clientId));
  }

  /** "" for null. */
  private static String orEmpty(String value) { return value == null ? "" : value; }

  /**
   * 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.
   */
  static final class ClientsServed {
    /** The distinct count, and whether the count stopped at the limit. */
    record Count(int count, boolean atLimit) {}

    private final int limit;
    // guards peerKeys and atLimit
    private final Object stateLock = new Object();
    // contractPeerKey values
    private final Set<String> peerKeys = new HashSet<>();
    private boolean atLimit;

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

    /** Counts the peer of one provider contract; "" counts nothing. */
    void add(String peerKey) {
      if (peerKey == null || peerKey.isEmpty()) {
        return;
      }
      synchronized (stateLock) {
        if (peerKeys.contains(peerKey)) {
          return;
        }
        if (limit <= peerKeys.size()) {
          atLimit = true;
          return;
        }
        peerKeys.add(peerKey);
      }
    }

    /** The current count. */
    Count count() {
      synchronized (stateLock) {
        return new Count(peerKeys.size(), atLimit);
      }
    }
  }
}