Developer SDK

TypeScript examples

Install the SDK · View source on GitHub ↗

provider/status.ts

typescript
// 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. These functions mirror the
// Go provider's status.go and are pure, so the self-test checks them without a
// network, credentials or the native companion. The companion counts the
// clients served with the contract's peer rules and serves every device value
// on its /provider-status route.

// 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.
export const 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.`;

export const providerStateStopped = "stopped";
// the platform disconnected this client for its network's client limit, and
// the SDK holds off reconnecting until the retry time
export const providerStateClientLimit = "client limit";
export const providerStateStarting = "starting";
export const providerStatePaused = "paused";
export const providerStateProviding = "providing";

// the payout wallet before the first wallet read finishes
export const payoutWalletChecking = "checking";
// the payout wallet when the first wallet read failed
export const payoutWalletUnavailable = "unavailable";
// the payout wallet when no wallet is mapped
export const payoutWalletNotSet = "not set";

export const payoutWalletScopeHotkey = "hotkey";
export const payoutWalletScopeProvider = "this provider";
export const payoutWalletScopeNetwork = "network";
export const payoutWalletScopeAnotherProvider = "another provider";

// the SDK's ProvideModePublic
export const provideModePublic = 3;
// the SDK's ClientLimitStatusExceeded
export const clientLimitStatusExceeded = "client_limit_exceeded";
// The consent_scope of a network's hotkey delegation entry in GET /sn/wallet.
// Hotkey delegations come with a later server and SDK change; the app only
// labels the entry.
export const snWalletConsentScopeHotkey = "hotkey";

// The companion counts distinct clients up to this many; beyond it the count is
// a lower bound, shown with a trailing "+".
export const clientsServedLimit = 100 * 1000;

const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

// One status snapshot.
export interface ProviderStatus {
  state: string;
  // the end of the client limit hold in unix milliseconds, shown with the
  // client limit state; 0 when unknown
  clientLimitRetryTime: number;
  clientsServed: number;
  clientsServedAtLimit: boolean;
  dataProvidedByteCount: number;
  // a coldkey ss58 address, or checking, unavailable, not set
  payoutWallet: string;
  // "" unless payoutWallet is an address
  payoutWalletScope: string;
}

// The device values that decide the providing state.
export interface ProviderStateValues {
  provideMode: number;
  clientLimitStatus: string;
  providePaused: boolean;
  provideEnabled: boolean;
  providerConnected: boolean;
}

// The payout wallet as the status shows it.
export interface PayoutWallet {
  payoutWallet: string;
  payoutWalletScope: string;
}

// The byte counts of the provider packet stats as the companion serves them,
// with the SDK's Go field names; their sum is the data provided.
export interface ProviderPacketStats {
  RemoteEgressByteCount: number;
  RemoteIngressByteCount: number;
}

// The companion's /provider-status body, checked.
export interface CompanionStatus extends ProviderStateValues {
  clientLimitRetryTime: number;
  providerPacketStats: ProviderPacketStats | null;
  clientsServed: number;
  clientsServedAtLimit: boolean;
  deviceRpcStarted: boolean;
}

// The lowercase form of a UUID, or "" for anything else.
export function normalizeId(text: unknown): string {
  return typeof text === "string" && uuidPattern.test(text) ? text.toLowerCase() : "";
}

// 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. A tie rounds to the even
// tenth, as Go's %.1f does in the reference, so 1280 bytes is "1.2 KiB"; the
// tenths are exact because the byte count is divided by powers of two.
export function formatByteCount(byteCount: number): string {
  if (byteCount < 1024) {
    return `${byteCount} B`;
  }
  const units = ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB"];
  const roundTenths = (value: number): number => {
    const tenths = value * 10;
    const whole = Math.floor(tenths);
    const fraction = tenths - whole;
    return fraction < 0.5 || (fraction === 0.5 && whole % 2 === 0) ? whole : whole + 1;
  };
  let value = byteCount / 1024;
  let unitIndex = 0;
  while (unitIndex < units.length - 1 && 10240 <= roundTenths(value)) {
    value /= 1024;
    unitIndex += 1;
  }
  return `${(roundTenths(value) / 10).toFixed(1)} ${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".
export function providerStatusText(state: string, clientLimitRetryTime: number): string {
  if (state !== providerStateClientLimit || !(0 < clientLimitRetryTime)) {
    return state;
  }
  const minuteMillis = 60 * 1000;
  const retryMinute = Math.floor((clientLimitRetryTime + minuteMillis - 1) / minuteMillis);
  const retryTime = new Date(retryMinute * minuteMillis);
  const hours = String(retryTime.getUTCHours()).padStart(2, "0");
  const minutes = String(retryTime.getUTCMinutes()).padStart(2, "0");
  return `${providerStateClientLimit}, retry at ${hours}:${minutes} UTC`;
}

// The providing state, 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.
export function providerState(values: ProviderStateValues): string {
  if (values.provideMode !== provideModePublic) {
    return providerStateStopped;
  }
  if (values.clientLimitStatus === clientLimitStatusExceeded) {
    return providerStateClientLimit;
  }
  if (values.providePaused) {
    return providerStatePaused;
  }
  if (values.provideEnabled && values.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.
export function payoutWalletScope(walletConsentScope: string, walletClientId: string, clientId: string): string {
  if (walletConsentScope === snWalletConsentScopeHotkey) {
    return payoutWalletScopeHotkey;
  }
  if (!walletClientId) {
    return payoutWalletScopeNetwork;
  }
  if (walletClientId.toLowerCase() === clientId.toLowerCase()) {
    return payoutWalletScopeProvider;
  }
  return payoutWalletScopeAnotherProvider;
}

// The payout wallet of a GET /sn/wallet result read with this client's JWT.
// Its wallet is the effective wallet of the client session (the contract's
// order: own provider consent, network consent, hotkey delegation, own other
// wallet, network-level copy). Returns null for an error result, which the
// app treats as a failed read.
export function payoutWalletFromResult(result: unknown, clientId: string): PayoutWallet | null {
  if (result === null || typeof result !== "object" || ("error" in result && result.error)) {
    return null;
  }
  const wallet = "wallet" in result ? result.wallet : undefined;
  if (wallet === null || typeof wallet !== "object" || !("coldkey_ss58" in wallet) ||
      typeof wallet.coldkey_ss58 !== "string" || wallet.coldkey_ss58 === "") {
    return {payoutWallet: payoutWalletNotSet, payoutWalletScope: ""};
  }
  const walletConsentScope = "consent_scope" in wallet && typeof wallet.consent_scope === "string" ? wallet.consent_scope : "";
  const walletClientId = "client_id" in wallet && typeof wallet.client_id === "string" ? wallet.client_id : "";
  return {
    payoutWallet: wallet.coldkey_ss58,
    payoutWalletScope: payoutWalletScope(walletConsentScope, walletClientId, clientId),
  };
}

// Data provided: the bytes relayed for clients in both directions since the
// device started, RemoteEgressByteCount + RemoteIngressByteCount of the
// provider packet stats; 0 when the stats are null.
export function dataProvidedByteCount(providerPacketStats: ProviderPacketStats | null): number {
  if (providerPacketStats === null) {
    return 0;
  }
  return providerPacketStats.RemoteEgressByteCount + providerPacketStats.RemoteIngressByteCount;
}

// The status line, for example
// "status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: 5Grw... (network)".
export function statusLine(status: ProviderStatus): string {
  const clientsServed = `${status.clientsServed}${status.clientsServedAtLimit ? "+" : ""}`;
  const payoutWallet = status.payoutWalletScope ? `${status.payoutWallet} (${status.payoutWalletScope})` : status.payoutWallet;
  return `status: ${providerStatusText(status.state, status.clientLimitRetryTime)} | clients served: ${clientsServed} | data provided: ${formatByteCount(status.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.
export function statusKey(status: ProviderStatus): string {
  return JSON.stringify([
    providerStatusText(status.state, status.clientLimitRetryTime),
    status.clientsServed,
    status.clientsServedAtLimit,
    status.payoutWallet,
    status.payoutWalletScope,
  ]);
}

// The companion's /provider-status body (javascript/integration/companion,
// provider mode), checked: every device value of the status, with the SDK's Go
// field names, the clients served that the companion counts, and whether its
// device rpc is served.
export function parseCompanionStatus(text: string): CompanionStatus {
  const body: unknown = JSON.parse(text);
  const fields = typeof body === "object" && body !== null ? body as Record<string, unknown> : {};
  const clientLimitStatus = typeof fields.ClientLimitStatus === "object" && fields.ClientLimitStatus !== null
    ? fields.ClientLimitStatus as Record<string, unknown>
    : {};
  const byteCount = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && 0 <= value;
  const packetStats = fields.ProviderPacketStats;
  let providerPacketStats: ProviderPacketStats | null = null;
  if (packetStats !== null) {
    const packetStatsFields = typeof packetStats === "object" && packetStats !== undefined ? packetStats as Record<string, unknown> : {};
    const {RemoteEgressByteCount: remoteEgressByteCount, RemoteIngressByteCount: remoteIngressByteCount} = packetStatsFields;
    if (!byteCount(remoteEgressByteCount) || !byteCount(remoteIngressByteCount)) {
      throw new Error("the companion answered an unexpected provider status");
    }
    providerPacketStats = {RemoteEgressByteCount: remoteEgressByteCount, RemoteIngressByteCount: remoteIngressByteCount};
  }
  const {
    ProvideMode: provideMode,
    ProvideEnabled: provideEnabled,
    ProvidePaused: providePaused,
    ProviderConnected: providerConnected,
    ClientsServed: clientsServed,
    ClientsServedAtLimit: clientsServedAtLimit,
    DeviceRpcStarted: deviceRpcStarted,
  } = fields;
  const {Status: status, RetryTime: retryTime} = clientLimitStatus;
  if (typeof provideMode !== "number" || !Number.isInteger(provideMode) || typeof provideEnabled !== "boolean" ||
      typeof providePaused !== "boolean" || typeof providerConnected !== "boolean" || typeof status !== "string" ||
      typeof retryTime !== "number" || !Number.isSafeInteger(retryTime) || !byteCount(clientsServed) ||
      typeof clientsServedAtLimit !== "boolean" || typeof deviceRpcStarted !== "boolean") {
    throw new Error("the companion answered an unexpected provider status");
  }
  return {
    provideMode,
    provideEnabled,
    providePaused,
    providerConnected,
    clientLimitStatus: status,
    clientLimitRetryTime: retryTime,
    providerPacketStats,
    clientsServed,
    clientsServedAtLimit,
    deviceRpcStarted,
  };
}

// The status from the companion's last /provider-status read (null before the
// first one, which shows "starting") and the payout wallet read.
export function providerStatus(companionStatus: CompanionStatus | null, payoutWallet: string, payoutWalletScope: string): ProviderStatus {
  if (companionStatus === null) {
    return {
      state: providerStateStarting,
      clientLimitRetryTime: 0,
      clientsServed: 0,
      clientsServedAtLimit: false,
      dataProvidedByteCount: 0,
      payoutWallet,
      payoutWalletScope,
    };
  }
  return {
    state: providerState(companionStatus),
    clientLimitRetryTime: companionStatus.clientLimitRetryTime,
    clientsServed: companionStatus.clientsServed,
    clientsServedAtLimit: companionStatus.clientsServedAtLimit,
    dataProvidedByteCount: dataProvidedByteCount(companionStatus.providerPacketStats),
    payoutWallet,
    payoutWalletScope,
  };
}