react-native-pirate-wallet 0.3.2 → 0.3.3

package/README.md

@@ -240,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.2",
+  "version": "0.3.3",
   "description": "React Native wrapper for the Pirate Unified Wallet native SDK surfaces",
   "keywords": [
     "react-native",
@@ -52,11 +52,11 @@
     "react-native": ">=0.71.0 <1.0.0"
   },
   "optionalDependencies": {
-    "react-native-pirate-wallet-android": "0.3.2",
-    "react-native-pirate-wallet-android-x86_64": "0.3.2",
-    "react-native-pirate-wallet-ios-device": "0.3.2",
-    "react-native-pirate-wallet-ios-simulator-arm64": "0.3.2",
-    "react-native-pirate-wallet-ios-simulator-x86_64": "0.3.2"
+    "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/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')