react-native-pirate-wallet 0.3.0 → 0.3.3

package/README.md

@@ -77,7 +77,9 @@ await sdk.configureAccountStorage({
 - `src/`
 
 Native libraries are distributed in exact-version Android ARM, Android x86_64,
-iOS device, and iOS simulator companion packages.
+iOS device, iOS simulator arm64, and iOS simulator x86_64 companion packages.
+On macOS, CocoaPods combines the two thin simulator archives into the universal
+XCFramework slice expected by Xcode.
 
 ## Preparing native artifacts in this repo
 
@@ -90,7 +92,8 @@ bash scripts/prepare-react-native-plugin.sh
 That copies:
 
 - Android JNI libraries into the two Android companion packages
-- iOS XCFramework slices into the two iOS companion packages
+- the iOS device XCFramework slice and two thin simulator archives into the
+  three iOS companion packages
 
 There is also a minimal consumer app in:
 
@@ -237,6 +240,85 @@ active wallet between running wallets.
     - `coinType`
     - `rpcPort`
     - `defaultBirthday`
+
+### Lightwalletd endpoints and failover pools
+
+Endpoint configuration is wallet-scoped. The recommended integration flow is
+to test candidate servers, save one primary plus its alternates, and then start
+or restart that wallet's synchronizer:
+
+```js
+const primary = 'https://lightd1.pirate.black:443'
+const alternates = [
+  'https://lightwalletd1.cryptoforge.cc:443',
+  'https://pirate.mathnodes.com:443'
+]
+
+const tests = await Promise.all(
+  [primary, ...alternates].map(url => sdk.testLightdEndpoint({ url }))
+)
+
+if (tests.every(result => result.success)) {
+  await sdk.setLightdEndpointPool({
+    walletId,
+    url: primary,
+    failoverEndpoints: alternates
+  })
+}
+
+const saved = await sdk.getLightdEndpointConfig(walletId)
+```
+
+- `getLightdEndpoint(walletId)`
+  - RPC: `get_lightd_endpoint`
+  - returns the effective primary endpoint URL
+- `getLightdEndpointConfig(walletId)`
+  - RPC: `get_lightd_endpoint_config`
+  - returns `LightdEndpointConfig`:
+    - `host`
+    - `port`
+    - `useTls`
+    - `tlsPin`
+    - `label`
+    - `automaticFailover`
+    - `failoverEndpoints`
+    - `isConfigured`
+- `testLightdEndpoint({ url, tlsPin? })`
+  - RPC: `test_node`
+  - also accepts `testLightdEndpoint(url, tlsPin?)`
+  - tests through the currently selected Direct, Tor, SOCKS5, or I2P transport
+  - reports success, height, latency, transport, TLS/pin information, server
+    version, chain name, and any connection error
+- `setLightdEndpoint({ walletId, url, tlsPin? })`
+  - RPC: `set_lightd_endpoint`
+  - also accepts `setLightdEndpoint(walletId, url, tlsPin?)`
+  - saves one primary and clears any previously configured failover pool
+- `setLightdEndpointPool({ walletId, url, failoverEndpoints, tlsPin? })`
+  - RPC: `set_lightd_endpoint_pool`
+  - also accepts
+    `setLightdEndpointPool(walletId, url, failoverEndpoints, tlsPin?)`
+  - saves the primary and up to 16 explicit alternates
+  - an empty `failoverEndpoints` array disables automatic failover
+
+Pool membership is validated by the backend before anything is persisted.
+Every member must resolve to the same recognized Pirate network, use the same
+clearnet, onion, or I2P route, and use the same HTTP/TLS security mode as the
+primary. The primary is removed from the alternate list and duplicate
+alternates are collapsed. A pinned primary cannot use automatic failover,
+because one server's SPKI pin cannot authenticate unrelated servers; use
+`setLightdEndpoint()` when pinning a single server.
+
+Saving either endpoint form cancels an existing sync session for that wallet so
+it cannot continue against stale connection state. Restart the synchronizer
+after the setter resolves. Pool candidates are still checked for compatible
+chain identity and history before failover or historical work is assigned; the
+array order is not a request to trust a candidate blindly.
+
+`testLightdEndpoint()` returns a structured failure result for connection-level
+failures. Invalid setter input or a rejected pool throws through the normal SDK
+promise, so applications should show the error and retain the previous saved
+configuration.
+
 - `formatAmount(arrrtoshis)`
   - RPC: `format_amount`
   - returns formatted string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-pirate-wallet",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "React Native wrapper for the Pirate Unified Wallet native SDK surfaces",
   "keywords": [
     "react-native",
@@ -52,10 +52,11 @@
     "react-native": ">=0.71.0 <1.0.0"
   },
   "optionalDependencies": {
-    "react-native-pirate-wallet-android": "0.3.0",
-    "react-native-pirate-wallet-android-x86_64": "0.3.0",
-    "react-native-pirate-wallet-ios-device": "0.3.0",
-    "react-native-pirate-wallet-ios-simulator": "0.3.0"
+    "react-native-pirate-wallet-android": "0.3.3",
+    "react-native-pirate-wallet-android-x86_64": "0.3.3",
+    "react-native-pirate-wallet-ios-device": "0.3.3",
+    "react-native-pirate-wallet-ios-simulator-arm64": "0.3.3",
+    "react-native-pirate-wallet-ios-simulator-x86_64": "0.3.3"
   },
   "publishConfig": {
     "access": "public"

package/scripts/assemble-ios-framework.js

@@ -1,18 +1,23 @@
-'use strict';
+"use strict";
 
-const fs = require('fs');
-const path = require('path');
+const childProcess = require("child_process");
+const fs = require("fs");
+const path = require("path");
 
-const packageRoot = path.resolve(__dirname, '..');
-const frameworkName = 'PirateWalletNative.xcframework';
-const iosPackages = [
+const packageRoot = path.resolve(__dirname, "..");
+const frameworkName = "PirateWalletNative.xcframework";
+const devicePackage = {
+  name: "react-native-pirate-wallet-ios-device",
+  slice: "ios-arm64",
+};
+const simulatorPackages = [
   {
-    name: 'react-native-pirate-wallet-ios-device',
-    slice: 'ios-arm64',
+    name: "react-native-pirate-wallet-ios-simulator-arm64",
+    architecture: "arm64",
   },
   {
-    name: 'react-native-pirate-wallet-ios-simulator',
-    slice: 'ios-arm64_x86_64-simulator',
+    name: "react-native-pirate-wallet-ios-simulator-x86_64",
+    architecture: "x86_64",
   },
 ];
 
@@ -22,43 +27,41 @@ function candidatePackageJsonPaths(packageName) {
     candidates.push(
       require.resolve(`${packageName}/package.json`, {
         paths: [process.cwd(), packageRoot],
-      }),
+      })
     );
   } catch (_) {
     // The monorepo package is resolved below before it has been published.
   }
-  candidates.push(
-    path.resolve(packageRoot, '..', packageName, 'package.json'),
-  );
+  candidates.push(path.resolve(packageRoot, "..", packageName, "package.json"));
   return [...new Set(candidates)];
 }
 
 function resolvePackage(packageName, expectedVersion) {
   for (const packageJsonPath of candidatePackageJsonPaths(packageName)) {
-    if (!fs.statSync(packageJsonPath, {throwIfNoEntry: false})?.isFile()) {
+    if (!fs.statSync(packageJsonPath, { throwIfNoEntry: false })?.isFile()) {
       continue;
     }
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
     if (packageJson.name !== packageName) {
       continue;
     }
     if (packageJson.version !== expectedVersion) {
       throw new Error(
         `${packageName}@${packageJson.version} does not match ` +
-          `react-native-pirate-wallet@${expectedVersion}`,
+          `react-native-pirate-wallet@${expectedVersion}`
       );
     }
-    return path.dirname(packageJsonPath);
+    return { root: path.dirname(packageJsonPath), packageJson };
   }
   throw new Error(
     `${packageName}@${expectedVersion} is required to build ` +
-      'react-native-pirate-wallet for iOS',
+      "react-native-pirate-wallet for iOS"
   );
 }
 
 function linkTree(source, destination) {
-  fs.mkdirSync(destination, {recursive: true});
-  for (const entry of fs.readdirSync(source, {withFileTypes: true})) {
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
     const sourcePath = path.join(source, entry.name);
     const destinationPath = path.join(destination, entry.name);
     if (entry.isDirectory()) {
@@ -71,7 +74,7 @@ function linkTree(source, destination) {
     try {
       fs.linkSync(sourcePath, destinationPath);
     } catch (error) {
-      if (!['EXDEV', 'EPERM', 'EACCES', 'EMLINK'].includes(error.code)) {
+      if (!["EXDEV", "EPERM", "EACCES", "EMLINK"].includes(error.code)) {
         throw error;
       }
       fs.copyFileSync(sourcePath, destinationPath);
@@ -79,45 +82,140 @@ function linkTree(source, destination) {
   }
 }
 
+function runXcrun(args) {
+  const result = childProcess.spawnSync("xcrun", args, { encoding: "utf8" });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      `xcrun ${args.join(" ")} failed:\n${result.stderr || result.stdout}`
+    );
+  }
+  return result.stdout.trim();
+}
+
+function verifyArchitectures(archive, expected) {
+  const actual = runXcrun(["lipo", "-archs", archive]).split(/\s+/).sort();
+  const wanted = [...expected].sort();
+  if (JSON.stringify(actual) !== JSON.stringify(wanted)) {
+    throw new Error(
+      `${archive} has architectures ${actual.join(
+        ", "
+      )}; expected ${wanted.join(", ")}`
+    );
+  }
+}
+
+function assertMatchingFile(left, right, label) {
+  const leftData = fs.readFileSync(left);
+  const rightData = fs.readFileSync(right);
+  if (!leftData.equals(rightData)) {
+    throw new Error(`iOS binary packages contain different ${label}`);
+  }
+}
+
 function assemble() {
-  if (process.platform !== 'darwin' && !process.argv.includes('--force')) {
+  if (process.platform !== "darwin") {
+    if (process.argv.includes("--force")) {
+      throw new Error("iOS XCFramework assembly requires macOS and xcrun lipo");
+    }
     return;
   }
 
   const wrapperPackage = JSON.parse(
-    fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
+    fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")
   );
-  const resolved = iosPackages.map(({name, slice}) => {
-    const expectedVersion = wrapperPackage.optionalDependencies?.[name];
+  function resolveExact(descriptor) {
+    const expectedVersion =
+      wrapperPackage.optionalDependencies?.[descriptor.name];
     if (expectedVersion !== wrapperPackage.version) {
-      throw new Error(`${name} must use the exact wrapper version`);
+      throw new Error(`${descriptor.name} must use the exact wrapper version`);
     }
-    const root = resolvePackage(name, expectedVersion);
     return {
-      name,
-      slice,
-      framework: path.join(root, 'ios', 'Frameworks', frameworkName),
+      ...descriptor,
+      ...resolvePackage(descriptor.name, expectedVersion),
     };
-  });
+  }
 
-  const infoPlists = resolved.map(({framework}) =>
-    fs.readFileSync(path.join(framework, 'Info.plist')),
+  const device = resolveExact(devicePackage);
+  const simulators = simulatorPackages.map(resolveExact);
+  const deviceFramework = path.join(
+    device.root,
+    "ios",
+    "Frameworks",
+    frameworkName
   );
-  if (!infoPlists.slice(1).every(data => data.equals(infoPlists[0]))) {
-    throw new Error('iOS binary packages contain different XCFramework metadata');
+  const deviceSlice = path.join(deviceFramework, device.slice);
+  if (!fs.statSync(deviceSlice, { throwIfNoEntry: false })?.isDirectory()) {
+    throw new Error(
+      `${device.name} is missing XCFramework slice ${device.slice}`
+    );
   }
 
-  const output = path.join(packageRoot, 'ios', 'Frameworks', frameworkName);
-  fs.rmSync(output, {recursive: true, force: true});
-  fs.mkdirSync(output, {recursive: true});
-  fs.writeFileSync(path.join(output, 'Info.plist'), infoPlists[0]);
+  const simulatorInputs = simulators.map((simulator) => {
+    const metadata = simulator.packageJson.pirateWalletNative;
+    if (
+      metadata?.platform !== "ios-simulator" ||
+      JSON.stringify(metadata.architectures) !==
+        JSON.stringify([simulator.architecture])
+    ) {
+      throw new Error(
+        `${simulator.name} does not identify its expected simulator architecture`
+      );
+    }
+    const archive = path.join(simulator.root, "ios", "libpirate_ffi_native.a");
+    const headers = path.join(simulator.root, "ios", "Headers");
+    verifyArchitectures(archive, [simulator.architecture]);
+    return { ...simulator, archive, headers };
+  });
 
-  for (const {name, slice, framework} of resolved) {
-    const source = path.join(framework, slice);
-    if (!fs.statSync(source, {throwIfNoEntry: false})?.isDirectory()) {
-      throw new Error(`${name} is missing XCFramework slice ${slice}`);
+  const canonicalHeaders = path.join(deviceSlice, "Headers");
+  for (const simulator of simulatorInputs) {
+    for (const header of ["module.modulemap", "pirate_wallet_service.h"]) {
+      assertMatchingFile(
+        path.join(canonicalHeaders, header),
+        path.join(simulator.headers, header),
+        header
+      );
     }
-    linkTree(source, path.join(output, slice));
+  }
+
+  const frameworksRoot = path.join(packageRoot, "ios", "Frameworks");
+  fs.mkdirSync(frameworksRoot, { recursive: true });
+  const temporaryRoot = fs.mkdtempSync(
+    path.join(frameworksRoot, `${frameworkName}.tmp-`)
+  );
+  const output = path.join(frameworksRoot, frameworkName);
+  try {
+    fs.copyFileSync(
+      path.join(deviceFramework, "Info.plist"),
+      path.join(temporaryRoot, "Info.plist")
+    );
+    linkTree(deviceSlice, path.join(temporaryRoot, device.slice));
+
+    const simulatorSlice = path.join(
+      temporaryRoot,
+      "ios-arm64_x86_64-simulator"
+    );
+    linkTree(canonicalHeaders, path.join(simulatorSlice, "Headers"));
+    const universalArchive = path.join(
+      simulatorSlice,
+      "libpirate_ffi_native.a"
+    );
+    runXcrun([
+      "lipo",
+      "-create",
+      ...simulatorInputs.map((simulator) => simulator.archive),
+      "-output",
+      universalArchive,
+    ]);
+    verifyArchitectures(universalArchive, ["arm64", "x86_64"]);
+
+    fs.rmSync(output, { recursive: true, force: true });
+    fs.renameSync(temporaryRoot, output);
+  } finally {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
   }
 }
 

package/scripts/verify-package.js

@@ -1,9 +1,9 @@
-'use strict';
+"use strict";
 
-const fs = require('fs');
-const path = require('path');
+const fs = require("fs");
+const path = require("path");
 
-const packageRoot = path.resolve(__dirname, '..');
+const packageRoot = path.resolve(__dirname, "..");
 
 function fail(message) {
   console.error(`[react-native-pirate-wallet] ${message}`);
@@ -12,7 +12,7 @@ function fail(message) {
 
 function requireFile(relativePath) {
   const absolutePath = path.join(packageRoot, relativePath);
-  if (!fs.statSync(absolutePath, {throwIfNoEntry: false})?.isFile()) {
+  if (!fs.statSync(absolutePath, { throwIfNoEntry: false })?.isFile()) {
     fail(`Required package file is missing: ${relativePath}`);
     return;
   }
@@ -28,96 +28,117 @@ function rejectPath(relativePath) {
 }
 
 function collectFiles(directory) {
-  if (!fs.statSync(directory, {throwIfNoEntry: false})?.isDirectory()) {
+  if (!fs.statSync(directory, { throwIfNoEntry: false })?.isDirectory()) {
     return [];
   }
 
-  return fs.readdirSync(directory, {withFileTypes: true}).flatMap(entry => {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
     const entryPath = path.join(directory, entry.name);
     return entry.isDirectory() ? collectFiles(entryPath) : [entryPath];
   });
 }
 
 const packageJson = JSON.parse(
-  fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
+  fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")
 );
 
-if (packageJson.name !== 'react-native-pirate-wallet') {
+if (packageJson.name !== "react-native-pirate-wallet") {
   fail(`Unexpected package name: ${packageJson.name}`);
 }
 if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(packageJson.version)) {
-  fail(`Package version is not valid semantic versioning: ${packageJson.version}`);
+  fail(
+    `Package version is not valid semantic versioning: ${packageJson.version}`
+  );
 }
 if (packageJson.private === true) {
-  fail('The publishable package must not be marked private');
+  fail("The publishable package must not be marked private");
 }
-if (packageJson.repository?.url !== 'https://github.com/PirateNetwork/Pirate-Unified-Light-Wallet.git') {
-  fail('The repository URL must match the GitHub repository used for npm provenance');
+if (
+  packageJson.repository?.url !==
+  "https://github.com/PirateNetwork/Pirate-Unified-Light-Wallet.git"
+) {
+  fail(
+    "The repository URL must match the GitHub repository used for npm provenance"
+  );
 }
-if (packageJson.publishConfig?.access !== 'public') {
-  fail('publishConfig.access must remain public');
+if (packageJson.publishConfig?.access !== "public") {
+  fail("publishConfig.access must remain public");
 }
 
 [
-  'LICENSE-MIT',
-  'README.md',
-  'react-native.config.js',
-  'react-native-pirate-wallet.podspec',
-  'scripts/assemble-ios-framework.js',
-  'scripts/resolve-android-packages.js',
-  'test/smoke.js',
-  'src/index.js',
-  'src/index.d.ts',
-  'android/src/main/AndroidManifest.xml',
-  'android/src/main/java/com/pirate/wallet/reactnative/PirateWalletReactNativeModule.kt',
-  'ios/PirateWalletReactNative.m',
-  'ios/PirateWalletReactNative.swift',
+  "LICENSE-MIT",
+  "README.md",
+  "react-native.config.js",
+  "react-native-pirate-wallet.podspec",
+  "scripts/assemble-ios-framework.js",
+  "scripts/resolve-android-packages.js",
+  "test/smoke.js",
+  "src/index.js",
+  "src/index.d.ts",
+  "android/src/main/AndroidManifest.xml",
+  "android/src/main/java/com/pirate/wallet/reactnative/PirateWalletReactNativeModule.kt",
+  "ios/PirateWalletReactNative.m",
+  "ios/PirateWalletReactNative.swift",
 ].forEach(requireFile);
 
-if (process.argv.includes('--publish-layout')) {
+if (process.argv.includes("--publish-layout")) {
   [
-    'android/.gradle',
-    'android/build',
-    'android/src/main/jniLibs',
-    'ios/Frameworks/PirateWalletNative.xcframework',
+    "android/.gradle",
+    "android/build",
+    "android/src/main/jniLibs",
+    "ios/Frameworks/PirateWalletNative.xcframework",
   ].forEach(rejectPath);
 }
 
 const binaryPackageNames = [
-  'react-native-pirate-wallet-android',
-  'react-native-pirate-wallet-android-x86_64',
-  'react-native-pirate-wallet-ios-device',
-  'react-native-pirate-wallet-ios-simulator',
+  "react-native-pirate-wallet-android",
+  "react-native-pirate-wallet-android-x86_64",
+  "react-native-pirate-wallet-ios-device",
+  "react-native-pirate-wallet-ios-simulator-arm64",
+  "react-native-pirate-wallet-ios-simulator-x86_64",
 ];
 for (const binaryPackageName of binaryPackageNames) {
   if (
-    packageJson.optionalDependencies?.[binaryPackageName] !== packageJson.version
+    packageJson.optionalDependencies?.[binaryPackageName] !==
+    packageJson.version
   ) {
     fail(`${binaryPackageName} must use the same exact version as the wrapper`);
   }
 }
 
 if (
-  !process.argv.includes('--publish-layout') &&
-  (process.platform === 'darwin' || process.argv.includes('--all-platforms'))
+  !process.argv.includes("--publish-layout") &&
+  (process.platform === "darwin" || process.argv.includes("--all-platforms"))
 ) {
   const staticLibraries = collectFiles(
-    path.join(packageRoot, 'ios', 'Frameworks', 'PirateWalletNative.xcframework'),
-  ).filter(file => file.endsWith('.a'));
+    path.join(
+      packageRoot,
+      "ios",
+      "Frameworks",
+      "PirateWalletNative.xcframework"
+    )
+  ).filter((file) => file.endsWith(".a"));
   if (staticLibraries.length !== 2) {
-    fail('The iOS XCFramework must contain device and simulator static libraries');
+    fail(
+      "The iOS XCFramework must contain device and simulator static libraries"
+    );
   }
   for (const library of staticLibraries) {
     if (fs.statSync(library).size === 0) {
-      fail(`The iOS static library is empty: ${path.relative(packageRoot, library)}`);
+      fail(
+        `The iOS static library is empty: ${path.relative(
+          packageRoot,
+          library
+        )}`
+      );
     }
   }
 }
 
 try {
-  const {resolveAndroidJniLibsPaths} = require('./resolve-android-packages');
+  const { resolveAndroidJniLibsPaths } = require("./resolve-android-packages");
   if (resolveAndroidJniLibsPaths().length !== 2) {
-    fail('Both Android binary packages must resolve');
+    fail("Both Android binary packages must resolve");
   }
 } catch (error) {
   fail(error.message);

package/src/index.d.ts

@@ -42,6 +42,50 @@ export interface PirateWalletAccountStorageConfig {
   storagePath?: string | null
 }
 
+export interface LightdEndpointConfig {
+  host: string
+  port: number
+  useTls: boolean
+  tlsPin: string | null
+  label: string | null
+  automaticFailover: boolean
+  failoverEndpoints: string[]
+  isConfigured: boolean
+}
+
+export interface SetLightdEndpointRequest {
+  walletId: string
+  url: string
+  tlsPin?: string | null
+}
+
+export interface SetLightdEndpointPoolRequest extends SetLightdEndpointRequest {
+  failoverEndpoints: string[]
+}
+
+export interface TestLightdEndpointRequest {
+  url: string
+  tlsPin?: string | null
+}
+
+export interface NodeTestResult {
+  success: boolean
+  latestBlockHeight: number | null
+  transportMode: string
+  tlsEnabled: boolean
+  tlsPinMatched: boolean | null
+  expectedPin: string | null
+  actualPin: string | null
+  errorMessage: string | null
+  responseTimeMs: number
+  serverVersion: string | null
+  chainName: string | null
+}
+
+export interface Acknowledgement {
+  acknowledged: true
+}
+
 export interface SynchronizerSnapshot {
   walletId: string
   alias: string
@@ -209,6 +253,19 @@ export class PirateWalletSdk {
   isValidShieldedAddr(address: string): Promise<boolean>
   validateAddress(address: string): Promise<any>
   validateConsensusBranch(walletId: string): Promise<any>
+  getLightdEndpoint(walletId: string): Promise<string>
+  getLightdEndpointConfig(walletId: string): Promise<LightdEndpointConfig>
+  setLightdEndpoint(request: SetLightdEndpointRequest): Promise<Acknowledgement>
+  setLightdEndpoint(walletId: string, url: string, tlsPin?: string | null): Promise<Acknowledgement>
+  setLightdEndpointPool(request: SetLightdEndpointPoolRequest): Promise<Acknowledgement>
+  setLightdEndpointPool(
+    walletId: string,
+    url: string,
+    failoverEndpoints: string[],
+    tlsPin?: string | null
+  ): Promise<Acknowledgement>
+  testLightdEndpoint(request: TestLightdEndpointRequest): Promise<NodeTestResult>
+  testLightdEndpoint(url: string, tlsPin?: string | null): Promise<NodeTestResult>
   formatAmount(arrrtoshis: AmountInput): Promise<string>
   parseAmount(arrr: string): Promise<AmountString>
   getCurrentReceiveAddress(walletId: string): Promise<string>

package/src/index.js

@@ -83,6 +83,33 @@ function buildRequest(method, params = {}) {
   return JSON.stringify(request)
 }
 
+function requireNonEmptyString(value, name) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string.`)
+  }
+  return value
+}
+
+function optionalNonEmptyString(value, name) {
+  if (value === undefined || value === null) {
+    return null
+  }
+  return requireNonEmptyString(value, name)
+}
+
+function validateFailoverEndpoints(value) {
+  if (!Array.isArray(value)) {
+    throw new Error('failoverEndpoints must be an array of endpoint URL strings.')
+  }
+  if (value.length > 16) {
+    throw new Error('failoverEndpoints may contain at most 16 endpoint URLs.')
+  }
+
+  return value.map((endpoint, index) =>
+    requireNonEmptyString(endpoint, `failoverEndpoints[${index}]`)
+  )
+}
+
 function unwrapEnvelope(responseJson, method, options = {}) {
   const { camelizeResult = true } = options
   let envelope
@@ -667,6 +694,62 @@ class PirateWalletSdk {
     return this._call('validate_consensus_branch', { wallet_id: walletId })
   }
 
+  getLightdEndpoint(walletId) {
+    return this._call('get_lightd_endpoint', {
+      wallet_id: requireNonEmptyString(walletId, 'walletId')
+    })
+  }
+
+  getLightdEndpointConfig(walletId) {
+    return this._call('get_lightd_endpoint_config', {
+      wallet_id: requireNonEmptyString(walletId, 'walletId')
+    })
+  }
+
+  setLightdEndpoint(requestOrWalletId, url = null, tlsPin = null) {
+    const request =
+      typeof requestOrWalletId === 'object' && requestOrWalletId !== null
+        ? requestOrWalletId
+        : { walletId: requestOrWalletId, url, tlsPin }
+
+    return this._call('set_lightd_endpoint', {
+      wallet_id: requireNonEmptyString(request.walletId, 'walletId'),
+      url: requireNonEmptyString(request.url, 'url'),
+      tls_pin_opt: optionalNonEmptyString(request.tlsPin, 'tlsPin')
+    })
+  }
+
+  setLightdEndpointPool(
+    requestOrWalletId,
+    url = null,
+    failoverEndpoints = [],
+    tlsPin = null
+  ) {
+    const request =
+      typeof requestOrWalletId === 'object' && requestOrWalletId !== null
+        ? requestOrWalletId
+        : { walletId: requestOrWalletId, url, failoverEndpoints, tlsPin }
+
+    return this._call('set_lightd_endpoint_pool', {
+      wallet_id: requireNonEmptyString(request.walletId, 'walletId'),
+      url: requireNonEmptyString(request.url, 'url'),
+      tls_pin_opt: optionalNonEmptyString(request.tlsPin, 'tlsPin'),
+      failover_endpoints: validateFailoverEndpoints(request.failoverEndpoints)
+    })
+  }
+
+  testLightdEndpoint(requestOrUrl, tlsPin = null) {
+    const request =
+      typeof requestOrUrl === 'object' && requestOrUrl !== null
+        ? requestOrUrl
+        : { url: requestOrUrl, tlsPin }
+
+    return this._call('test_node', {
+      url: requireNonEmptyString(request.url, 'url'),
+      tls_pin: optionalNonEmptyString(request.tlsPin, 'tlsPin')
+    })
+  }
+
   formatAmount(arrrtoshis) {
     return this._call('format_amount', { arrrtoshis })
   }

package/test/smoke.js

@@ -48,6 +48,51 @@ function createMockNativeModule() {
           ])
         case 'get_active_wallet':
           return ok('wallet-1')
+        case 'get_lightd_endpoint':
+          assert.strictEqual(request.wallet_id, 'wallet-1')
+          return ok('https://lightd1.pirate.black:443')
+        case 'get_lightd_endpoint_config':
+          assert.strictEqual(request.wallet_id, 'wallet-1')
+          return ok({
+            host: 'lightd1.pirate.black',
+            port: 443,
+            use_tls: true,
+            tls_pin: null,
+            label: 'Primary',
+            automatic_failover: true,
+            failover_endpoints: ['https://lightwalletd1.cryptoforge.cc:443'],
+            is_configured: true
+          })
+        case 'set_lightd_endpoint':
+          assert.strictEqual(request.wallet_id, 'wallet-1')
+          assert.strictEqual(request.url, 'https://lightd1.pirate.black:443')
+          assert.strictEqual(request.tls_pin_opt, 'base64-spki-pin')
+          return ok({ acknowledged: true })
+        case 'set_lightd_endpoint_pool':
+          assert.strictEqual(request.wallet_id, 'wallet-1')
+          assert.strictEqual(request.url, 'https://lightd1.pirate.black:443')
+          assert.strictEqual(request.tls_pin_opt, undefined)
+          assert.deepStrictEqual(request.failover_endpoints, [
+            'https://lightwalletd1.cryptoforge.cc:443',
+            'https://pirate.mathnodes.com:443'
+          ])
+          return ok({ acknowledged: true })
+        case 'test_node':
+          assert.strictEqual(request.url, 'https://lightwalletd1.cryptoforge.cc:443')
+          assert.strictEqual(request.tls_pin, undefined)
+          return ok({
+            success: true,
+            latest_block_height: 4200000,
+            transport_mode: 'Direct',
+            tls_enabled: true,
+            tls_pin_matched: null,
+            expected_pin: null,
+            actual_pin: 'observed-pin',
+            error_message: null,
+            response_time_ms: 95,
+            server_version: 'lightwalletd',
+            chain_name: 'main'
+          })
         case 'current_receive_address':
           assert.strictEqual(request.wallet_id, 'wallet-1')
           return ok('pirate1current')
@@ -164,6 +209,52 @@ async function main() {
   const latestBirthdayHeight = await sdk.getLatestBirthdayHeight('wallet-1')
   assert.strictEqual(latestBirthdayHeight, 345678)
 
+  const endpoint = await sdk.getLightdEndpoint('wallet-1')
+  assert.strictEqual(endpoint, 'https://lightd1.pirate.black:443')
+
+  const endpointConfig = await sdk.getLightdEndpointConfig('wallet-1')
+  assert.strictEqual(endpointConfig.automaticFailover, true)
+  assert.deepStrictEqual(endpointConfig.failoverEndpoints, [
+    'https://lightwalletd1.cryptoforge.cc:443'
+  ])
+
+  const endpointTest = await sdk.testLightdEndpoint(
+    'https://lightwalletd1.cryptoforge.cc:443'
+  )
+  assert.strictEqual(endpointTest.latestBlockHeight, 4200000)
+  assert.strictEqual(endpointTest.responseTimeMs, 95)
+
+  const endpointAck = await sdk.setLightdEndpoint({
+    walletId: 'wallet-1',
+    url: 'https://lightd1.pirate.black:443',
+    tlsPin: 'base64-spki-pin'
+  })
+  assert.strictEqual(endpointAck.acknowledged, true)
+
+  const poolAck = await sdk.setLightdEndpointPool({
+    walletId: 'wallet-1',
+    url: 'https://lightd1.pirate.black:443',
+    failoverEndpoints: [
+      'https://lightwalletd1.cryptoforge.cc:443',
+      'https://pirate.mathnodes.com:443'
+    ]
+  })
+  assert.strictEqual(poolAck.acknowledged, true)
+
+  assert.throws(
+    () =>
+      sdk.setLightdEndpointPool({
+        walletId: 'wallet-1',
+        url: 'https://lightd1.pirate.black:443',
+        failoverEndpoints: 'not-an-array'
+      }),
+    /failoverEndpoints must be an array/
+  )
+  assert.throws(
+    () => sdk.testLightdEndpoint('  '),
+    /url must be a non-empty string/
+  )
+
   assert.strictEqual(await sdk.getCurrentAddress('wallet-1'), 'pirate1current')
   assert.strictEqual(await sdk.getNextAddress('wallet-1'), 'pirate1next')