Developer SDK

Electron examples

Install the SDK · View source on GitHub ↗

provider/test/status.test.mjs

javascript
// The status rules of PROVIDER_CONTRACT.md ("Status", "Self-test"): the
// disclaimer, the byte, status text, status line, status rule and payout
// wallet scope vectors, and reading the companion's /provider-status body into
// the four fields. The peer key and clients-served vectors are the
// companion's (javascript/integration/companion, provider_test.go), which
// counts the clients served. No Electron, network or credentials.

import {test} from "node:test";
import assert from "node:assert/strict";
import {createHash} from "node:crypto";
import {readFileSync} from "node:fs";
import {
  clientLimitStatusExceeded,
  clientLimitStatusNone,
  consentDisclaimer,
  dataProvidedByteCount,
  formatByteCount,
  parseProviderStatus,
  payoutWalletChecking,
  payoutWalletNotSet,
  payoutWalletScope,
  payoutWalletScopeAnotherProvider,
  payoutWalletScopeHotkey,
  payoutWalletScopeNetwork,
  payoutWalletScopeProvider,
  provideModeNetwork,
  provideModeNone,
  provideModePublic,
  providerState,
  providerStateClientLimit,
  providerStatePaused,
  providerStateProviding,
  providerStateStarting,
  providerStateStopped,
  providerStatusText,
  statusFields,
  statusLine,
} from "../status.mjs";

// sha-256 of the consent disclaimer (utf-8, lf line breaks, no trailing
// newline), published in PROVIDER_CONTRACT.md for every example to check
const consentDisclaimerSha256 = "83edee1e45cccd5deb6b86755cc5f6a91b6ade26e7eefc1e7670b5833a95502c";

// the public Substrate development account, test data only
const walletA = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";

const provider = "11111111-1111-1111-1111-111111111111";
const clientA = "22222222-2222-2222-2222-222222222222";

// A /provider-status body in the companion's shape, with changes.
function providerStatusBody(changes = {}) {
  return {
    ProvideMode: 3,
    ProvideEnabled: true,
    ProvidePaused: false,
    ProviderConnected: true,
    ClientLimitStatus: {Status: "", RetryTime: 0},
    ProviderPacketStats: {RemoteEgressByteCount: 13000000, RemoteIngressByteCount: 2342},
    ClientsServed: 3,
    ClientsServedAtLimit: false,
    DeviceRpcStarted: true,
    ...changes,
  };
}

// The four fields for a /provider-status body and a payout wallet.
function routeFields(body, payoutWallet = walletA, payoutWalletScope = payoutWalletScopeNetwork) {
  const deviceValues = parseProviderStatus(body);
  return statusFields({
    state: providerState(deviceValues),
    clientLimitRetryTime: deviceValues.clientLimitRetryTime,
    clientsServed: deviceValues.clientsServed,
    clientsServedAtLimit: deviceValues.clientsServedAtLimit,
    dataProvidedByteCount: deviceValues.dataProvidedByteCount,
    payoutWallet,
    payoutWalletScope,
  });
}

test("the consent disclaimer is the contract's exact text", () => {
  const digest = createHash("sha256").update(consentDisclaimer, "utf8").digest("hex");
  assert.equal(digest, consentDisclaimerSha256);
});

test("the window shows the disclaimer next to start with the same text", () => {
  const html = readFileSync(new URL("../renderer/index.html", import.meta.url), "utf8");
  const match = /<p id="disclaimer"[^>]*>([^<]*)<\/p>/.exec(html);
  assert.ok(match, "index.html has the disclaimer paragraph");
  assert.equal(match[1].replaceAll("\r\n", "\n"), consentDisclaimer);
  assert.ok(html.indexOf('id="disclaimer"') < html.indexOf('id="start"'));
});

test("byte counts use binary units with one decimal", () => {
  const cases = [
    {byteCount: 0, text: "0 B"},
    {byteCount: 1023, text: "1023 B"},
    {byteCount: 1024, text: "1.0 KiB"},
    {byteCount: 1536, text: "1.5 KiB"},
    // exact halves round to even (contract addendum 45c5d3f); toFixed would show 1.3 KiB
    {byteCount: 1280, text: "1.2 KiB"},
    {byteCount: 1792, text: "1.8 KiB"},
    {byteCount: 1048575, text: "1.0 MiB"},
    {byteCount: 13002342, text: "12.4 MiB"},
    {byteCount: 5 * 1024 * 1024 * 1024, text: "5.0 GiB"},
    {byteCount: 3 * 1024 * 1024 * 1024 * 1024, text: "3.0 TiB"},
  ];
  for (const c of cases) {
    assert.equal(formatByteCount(c.byteCount), c.text, `${c.byteCount} bytes`);
  }
});

test("byte counts round like the go provider's %.1f on more halves and at the unit edges", () => {
  // the go provider's output for these counts
  const cases = [
    {byteCount: 1331, text: "1.3 KiB"},
    {byteCount: 2304, text: "2.2 KiB"},
    {byteCount: 2816, text: "2.8 KiB"},
    {byteCount: 1048524, text: "1023.9 KiB"},
    {byteCount: 2 ** 62, text: "4.0 EiB"},
    {byteCount: 2 ** 63, text: "8.0 EiB"},
  ];
  for (const c of cases) {
    assert.equal(formatByteCount(c.byteCount), c.text, `${c.byteCount} bytes`);
  }
});

test("the client limit status names the retry time rounded up to the minute in utc", () => {
  const cases = [
    // 2026-10-06 19:05:00.000 UTC, exactly on a minute
    {state: providerStateClientLimit, clientLimitRetryTime: 1791313500000, text: "client limit, retry at 19:05 UTC"},
    // 19:04:00.001 rounds up, so the shown time is never before the retry
    {state: providerStateClientLimit, clientLimitRetryTime: 1791313440001, text: "client limit, retry at 19:05 UTC"},
    // no retry time
    {state: providerStateClientLimit, clientLimitRetryTime: 0, text: "client limit"},
    // 23:59:00.001 rolls over the hour and the day
    {state: providerStateClientLimit, clientLimitRetryTime: 1791331140001, text: "client limit, retry at 00:00 UTC"},
    {state: providerStateStarting, clientLimitRetryTime: 1791313500000, text: "starting"},
  ];
  for (const c of cases) {
    assert.equal(providerStatusText(c.state, c.clientLimitRetryTime), c.text, `${c.state} retrying at ${c.clientLimitRetryTime}`);
  }
});

test("the status line and fields match the contract's golden lines", () => {
  const cases = [
    {
      status: {state: providerStateStarting, clientLimitRetryTime: 0, clientsServed: 0, clientsServedAtLimit: false, dataProvidedByteCount: 0, payoutWallet: payoutWalletChecking, payoutWalletScope: ""},
      line: "status: starting | clients served: 0 | data provided: 0 B | payout wallet: checking",
    },
    {
      status: {state: providerStateProviding, clientLimitRetryTime: 0, clientsServed: 3, clientsServedAtLimit: false, dataProvidedByteCount: 13002342, payoutWallet: walletA, payoutWalletScope: payoutWalletScopeNetwork},
      line: `status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: ${walletA} (network)`,
    },
    {
      status: {state: providerStateProviding, clientLimitRetryTime: 0, clientsServed: 3, clientsServedAtLimit: false, dataProvidedByteCount: 13002342, payoutWallet: walletA, payoutWalletScope: payoutWalletScopeHotkey},
      line: `status: providing | clients served: 3 | data provided: 12.4 MiB | payout wallet: ${walletA} (hotkey)`,
    },
    {
      status: {state: providerStatePaused, clientLimitRetryTime: 0, clientsServed: 100 * 1000, clientsServedAtLimit: true, dataProvidedByteCount: 1536, payoutWallet: walletA, payoutWalletScope: payoutWalletScopeProvider},
      line: `status: paused | clients served: 100000+ | data provided: 1.5 KiB | payout wallet: ${walletA} (this provider)`,
    },
    {
      status: {state: providerStateStopped, clientLimitRetryTime: 0, clientsServed: 0, clientsServedAtLimit: false, dataProvidedByteCount: 0, payoutWallet: payoutWalletNotSet, payoutWalletScope: ""},
      line: "status: stopped | clients served: 0 | data provided: 0 B | payout wallet: not set",
    },
    {
      status: {state: providerStateClientLimit, clientLimitRetryTime: 1791313500000, clientsServed: 0, clientsServedAtLimit: false, dataProvidedByteCount: 0, payoutWallet: walletA, payoutWalletScope: payoutWalletScopeNetwork},
      line: `status: client limit, retry at 19:05 UTC | clients served: 0 | data provided: 0 B | payout wallet: ${walletA} (network)`,
    },
  ];
  for (const c of cases) {
    assert.equal(statusLine(c.status), c.line);
    const fields = statusFields(c.status);
    assert.equal(`status: ${fields.status} | clients served: ${fields.clientsServed} | data provided: ${fields.dataProvided} | payout wallet: ${fields.payoutWallet}`, c.line);
  }
});

test("a new client limit retry time changes the status field", () => {
  const status = {state: providerStateClientLimit, clientLimitRetryTime: 1791313500000, clientsServed: 0, clientsServedAtLimit: false, dataProvidedByteCount: 0, payoutWallet: payoutWalletChecking, payoutWalletScope: ""};
  // 19:25 UTC
  const retried = {...status, clientLimitRetryTime: 1791314700000};
  assert.notEqual(statusFields(retried).status, statusFields(status).status);
  assert.equal(statusFields(retried).status, "client limit, retry at 19:25 UTC");
});

test("the providing state follows the mode, client limit, pause, enable and connected rules in order", () => {
  const cases = [
    {provideMode: provideModeNone, clientLimitStatus: clientLimitStatusNone, providePaused: false, provideEnabled: false, providerConnected: false, state: providerStateStopped},
    {provideMode: provideModeNetwork, clientLimitStatus: clientLimitStatusNone, providePaused: false, provideEnabled: true, providerConnected: true, state: providerStateStopped},
    {provideMode: provideModePublic, clientLimitStatus: clientLimitStatusNone, providePaused: false, provideEnabled: true, providerConnected: false, state: providerStateStarting},
    {provideMode: provideModePublic, clientLimitStatus: clientLimitStatusNone, providePaused: false, provideEnabled: false, providerConnected: true, state: providerStateStarting},
    {provideMode: provideModePublic, clientLimitStatus: clientLimitStatusNone, providePaused: false, provideEnabled: true, providerConnected: true, state: providerStateProviding},
    {provideMode: provideModePublic, clientLimitStatus: clientLimitStatusNone, providePaused: true, provideEnabled: true, providerConnected: true, state: providerStatePaused},
    // the contract's status rule vectors: the client limit comes after
    // stopped and before every other state
    {provideMode: provideModeNetwork, clientLimitStatus: clientLimitStatusExceeded, providePaused: false, provideEnabled: true, providerConnected: true, state: providerStateStopped},
    {provideMode: provideModePublic, clientLimitStatus: clientLimitStatusExceeded, providePaused: true, provideEnabled: true, providerConnected: true, state: providerStateClientLimit},
    {provideMode: provideModePublic, clientLimitStatus: clientLimitStatusExceeded, providePaused: false, provideEnabled: false, providerConnected: false, state: providerStateClientLimit},
    {provideMode: provideModePublic, clientLimitStatus: clientLimitStatusNone, providePaused: true, provideEnabled: true, providerConnected: true, state: providerStatePaused},
  ];
  for (const c of cases) {
    const {state, ...readout} = c;
    assert.equal(providerState(readout), state, JSON.stringify(readout));
  }
});

test("the payout wallet is labeled by its consent scope first, then by the owner of its mapping", () => {
  const cases = [
    // a hotkey delegation is network-level but not the network's wallet
    {walletConsentScope: "hotkey", walletClientId: "", scope: payoutWalletScopeHotkey},
    {walletConsentScope: "hotkey", walletClientId: provider, scope: payoutWalletScopeHotkey},
    {walletConsentScope: "network", walletClientId: "", scope: payoutWalletScopeNetwork},
    {walletConsentScope: "", walletClientId: "", scope: payoutWalletScopeNetwork},
    {walletConsentScope: "provider", walletClientId: provider, scope: payoutWalletScopeProvider},
    {walletConsentScope: "", walletClientId: provider, scope: payoutWalletScopeProvider},
    {walletConsentScope: "provider", walletClientId: clientA, scope: payoutWalletScopeAnotherProvider},
  ];
  for (const c of cases) {
    assert.equal(payoutWalletScope(c.walletConsentScope, c.walletClientId, provider), c.scope, JSON.stringify(c));
  }
});

test("the companion's status body reads into the device values", () => {
  assert.deepEqual(parseProviderStatus(providerStatusBody()), {
    provideMode: 3,
    provideEnabled: true,
    providePaused: false,
    providerConnected: true,
    clientLimitStatus: "",
    clientLimitRetryTime: 0,
    dataProvidedByteCount: 13002342,
    clientsServed: 3,
    clientsServedAtLimit: false,
  });
  // no provider: null stats provide 0 bytes
  assert.equal(parseProviderStatus(providerStatusBody({ProviderPacketStats: null})).dataProvidedByteCount, 0);
  assert.equal(dataProvidedByteCount(null), 0);
  assert.equal(dataProvidedByteCount({RemoteEgressByteCount: 5, RemoteIngressByteCount: 7}), 12);
});

test("the companion's status body shows the contract's fields", () => {
  const cases = [
    {body: providerStatusBody(), status: "providing", clientsServed: "3", dataProvided: "12.4 MiB"},
    {body: providerStatusBody({ClientsServed: 100 * 1000, ClientsServedAtLimit: true}), status: "providing", clientsServed: "100000+", dataProvided: "12.4 MiB"},
    {body: providerStatusBody({ProviderPacketStats: null, ClientsServed: 0, ProviderConnected: false}), status: "starting", clientsServed: "0", dataProvided: "0 B"},
    {body: providerStatusBody({ProvideEnabled: false}), status: "starting", clientsServed: "3", dataProvided: "12.4 MiB"},
    {body: providerStatusBody({ProvidePaused: true, ProviderPacketStats: {RemoteEgressByteCount: 1280, RemoteIngressByteCount: 0}}), status: "paused", clientsServed: "3", dataProvided: "1.2 KiB"},
    // the client limit comes after stopped and before paused, with its retry time
    {body: providerStatusBody({ProvidePaused: true, ClientLimitStatus: {Status: "client_limit_exceeded", RetryTime: 1791313440001}}), status: "client limit, retry at 19:05 UTC", clientsServed: "3", dataProvided: "12.4 MiB"},
    {body: providerStatusBody({ProviderConnected: false, ClientLimitStatus: {Status: "client_limit_exceeded", RetryTime: 0}}), status: "client limit", clientsServed: "3", dataProvided: "12.4 MiB"},
    {body: providerStatusBody({ProvideMode: 1, ClientLimitStatus: {Status: "client_limit_exceeded", RetryTime: 1791313500000}}), status: "stopped", clientsServed: "3", dataProvided: "12.4 MiB"},
    {body: providerStatusBody({ProvideMode: 0, ProvideEnabled: false, ProviderConnected: false}), status: "stopped", clientsServed: "3", dataProvided: "12.4 MiB"},
  ];
  for (const c of cases) {
    const fields = routeFields(c.body);
    assert.deepEqual(
      {status: fields.status, clientsServed: fields.clientsServed, dataProvided: fields.dataProvided},
      {status: c.status, clientsServed: c.clientsServed, dataProvided: c.dataProvided},
      JSON.stringify(c.body),
    );
  }
  // the payout wallet is the app's own read, labeled for this client
  assert.equal(routeFields(providerStatusBody(), walletA, payoutWalletScope("provider", clientA, provider)).payoutWallet, `${walletA} (another provider)`);
});

test("a status body that is not the companion's shape is refused", () => {
  const invalidBodies = [
    null,
    [],
    "providing",
    {},
    providerStatusBody({ProvideMode: "3"}),
    providerStatusBody({ProvideEnabled: undefined}),
    providerStatusBody({ProvidePaused: 0}),
    providerStatusBody({ProviderConnected: "true"}),
    providerStatusBody({ClientLimitStatus: null}),
    providerStatusBody({ClientLimitStatus: {Status: "", RetryTime: "0"}}),
    providerStatusBody({ClientLimitStatus: {Status: "", RetryTime: -1}}),
    providerStatusBody({ProviderPacketStats: {RemoteEgressByteCount: 5}}),
    providerStatusBody({ProviderPacketStats: {RemoteEgressByteCount: 5, RemoteIngressByteCount: 1.5}}),
    providerStatusBody({ProviderPacketStats: 12}),
    providerStatusBody({ClientsServed: -1}),
    providerStatusBody({ClientsServed: undefined}),
    providerStatusBody({ClientsServedAtLimit: "false"}),
  ];
  for (const body of invalidBodies) {
    assert.throws(() => parseProviderStatus(body), /unexpected provider status/, JSON.stringify(body));
  }
});