react-native-pirate-wallet 0.2.1

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pirate Chain Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,537 @@
+# react-native-pirate-wallet
+
+`react-native-pirate-wallet` is the React Native wrapper for the unified Pirate wallet backend.
+
+It exposes one JS API over the same native service layer used by the Android SDK and iOS SDK.
+
+The package is meant for React Native wallets such as Edge Wallet.
+
+Repo-level build and integration notes:
+
+- `docs/react-native-plugin.md`
+
+## What it wraps
+
+- Android: JNI bridge over `libpirate_ffi_native.so`
+- iOS: Objective-C bridge over `PirateWalletNative.xcframework`
+- JS: typed wallet wrapper plus a polling synchronizer
+
+The JS surface mirrors the SDK boundary used by the native Android and iOS SDKs.
+
+## Account-scoped wallet storage
+
+Configure wallet storage before any wallet operation:
+
+```js
+const sdk = createPirateWalletSdk()
+
+await sdk.configureAccountStorage({
+  accountId: edgeAccountIdHash,
+  passphrase: edgeAccountDerivedSecret
+})
+```
+
+The native module creates an app-private directory for that account and asks the
+Rust service to open or create that account's wallet namespace. The selected
+directory contains:
+
+- `wallet_registry.db`
+- per-wallet database files
+- database salts
+- sealed database key files
+
+The passphrase unlocks both the registry and the per-wallet databases in that
+namespace. It must be unique per local account and derived from high-entropy
+account secret material. Do not use a hardcoded passphrase, a public account ID,
+email address, or device ID as the passphrase.
+
+By default, Android derives the directory under:
+
+```text
+Context.filesDir/pirate_wallet/accounts/<sanitized-account-id>
+```
+
+iOS derives the directory under:
+
+```text
+Application Support/PirateWallet/accounts/<sanitized-account-id>
+```
+
+Integrations that need to provide their own app-private path may pass
+`storagePath`:
+
+```js
+await sdk.configureAccountStorage({
+  accountId: edgeAccountIdHash,
+  storagePath: accountPrivatePath,
+  passphrase: edgeAccountDerivedSecret
+})
+```
+
+## Repo layout
+
+- `android/`
+- `example/`
+- `ios/`
+- `scripts/`
+- `src/`
+
+The Android native libraries are distributed in the exact-version
+`react-native-pirate-wallet-android` companion package.
+
+## Preparing native artifacts in this repo
+
+Before testing or packaging this plugin from the monorepo, stage the native artifacts:
+
+```bash
+bash scripts/prepare-react-native-plugin.sh
+```
+
+That copies:
+
+- Android JNI libraries into `bindings/react-native-pirate-wallet-android/`
+- the iOS XCFramework into this package
+
+There is also a minimal consumer app in:
+
+- `bindings/react-native-pirate-wallet/example/`
+
+That app is used to verify install, autolinking, and a couple of real native calls.
+
+## Public JS surface
+
+Main exports:
+
+- `PirateWalletSdk`
+- `PirateWalletSynchronizer`
+- `createPirateWalletSdk()`
+
+The synchronizer is implemented in JS and polls the native service through the bridge. It does not depend on native event emitters.
+
+## RPC and API reference
+
+The JS wrapper is a typed layer over the native `invoke(requestJson, pretty)` bridge.
+
+Low-level entry points:
+
+- `sdk.invoke(requestJson, pretty = false)`
+  - sends a raw JSON request to the native bridge
+  - returns a JSON envelope string
+- `sdk.configureAccountStorage({ accountId, passphrase, storagePath? })`
+  - RPC: `configure_wallet_storage`
+  - selects an account-specific registry/database directory
+  - creates the registry with `passphrase` if it does not exist
+  - unlocks the existing registry with `passphrase` if it already exists
+  - clears loaded registry state, active wallet state, DB caches, and sync caches
+    before switching namespaces
+- `sdk.buildInfoJson(pretty = false)`
+  - raw JSON envelope for `get_build_info`
+- `sdk.buildInfo()`
+  - RPC: `get_build_info`
+  - returns:
+    - `version`
+    - `gitCommit`
+    - `buildDate`
+    - `rustVersion`
+    - `targetTriple`
+- `createPirateWalletSdk()`
+  - returns a new `PirateWalletSdk` instance backed by the linked native module
+
+The typed JS methods below unwrap the native JSON envelope and return the `result` value directly.
+
+### Amount wire format
+
+All arrrtoshi amount values on the JSON wire are decimal strings, not JSON
+numbers. This includes balances, transaction amounts, fees, pending
+transaction totals, payment disclosure amounts, and `parseAmount()` results.
+Amount request fields accept decimal strings, safe integer numbers, or
+`bigint`; the JS wrapper serializes them as strings before calling native code.
+
+### Wallet lifecycle
+
+- `walletRegistryExists()`
+  - RPC: `wallet_registry_exists`
+  - returns `boolean`
+- `listWallets()`
+  - RPC: `list_wallets`
+  - returns `WalletMeta[]`
+- `getActiveWalletId()`
+  - RPC: `get_active_wallet`
+  - returns `string | null`
+- `getActiveWallet()`
+  - helper over `getActiveWalletId()` and `listWallets()`
+  - returns `WalletMeta | null`
+- `getWallet(walletId)`
+  - helper over `listWallets()`
+  - returns `WalletMeta | null`
+- `createWallet(requestOrName, birthdayHeight?)`
+  - RPC: `create_wallet`
+  - request fields:
+    - `name`
+    - optional `birthdayHeight`
+    - optional `mnemonicLanguage`
+  - returns wallet id string
+- `restoreWallet(requestOrName, mnemonic?, birthdayHeight?, mnemonicLanguage?)`
+  - RPC: `restore_wallet`
+  - request fields:
+    - `name`
+    - `mnemonic`
+    - optional `birthdayHeight`
+    - optional `mnemonicLanguage`
+  - returns wallet id string
+- `importViewingWallet(requestOrName, saplingViewingKey?, ironwoodViewingKey?, birthdayHeight)`
+  - RPC: `import_viewing_wallet`
+  - request fields:
+    - `name`
+    - optional `saplingViewingKey`
+    - optional `ironwoodViewingKey`
+    - `birthdayHeight`
+  - returns wallet id string
+- `switchWallet(walletId)`
+  - RPC: `switch_wallet`
+  - returns acknowledgement object
+- `renameWallet(walletId, newName)`
+  - RPC: `rename_wallet`
+  - returns acknowledgement object
+- `deleteWallet(walletId)`
+  - RPC: `delete_wallet`
+  - returns acknowledgement object
+- `setWalletBirthdayHeight(walletId, birthdayHeight)`
+  - RPC: `set_wallet_birthday_height`
+  - returns acknowledgement object
+- `getLatestBirthdayHeight(walletId)`
+  - helper over `getWallet(walletId)`
+  - returns `number | null`
+
+#### Active wallet and wallet IDs
+
+Wallet metadata is stored in the backend registry. The registry also persists
+an active wallet ID, which acts as the SDK's current-wallet pointer for flows
+that need one. Integrations that already keep their own wallet selection can
+call wallet-scoped methods directly with `walletId`.
+
+`switchWallet(walletId)` updates the active-wallet pointer, records last-used
+metadata, and stops sync for the previously active wallet. Multi-wallet sync
+should be driven by wallet-scoped synchronizers rather than by switching the
+active wallet between running wallets.
+
+### Mnemonic, formatting, and network
+
+- `generateMnemonic(wordCount?, mnemonicLanguage?)`
+  - RPC: `generate_mnemonic`
+  - returns mnemonic string
+- `validateMnemonic(mnemonic, mnemonicLanguage?)`
+  - RPC: `validate_mnemonic`
+  - returns `boolean`
+- `inspectMnemonic(mnemonic)`
+  - RPC: `inspect_mnemonic`
+  - returns:
+    - `isValid`
+    - `detectedLanguage`
+    - `ambiguousLanguages`
+    - `wordCount`
+- `getNetworkInfo()`
+  - RPC: `get_network_info`
+  - returns:
+    - `name`
+    - `coinType`
+    - `rpcPort`
+    - `defaultBirthday`
+- `formatAmount(arrrtoshis)`
+  - RPC: `format_amount`
+  - returns formatted string
+- `parseAmount(arrr)`
+  - RPC: `parse_amount`
+  - returns integer arrrtoshis as a decimal string
+
+### Validation
+
+- `isValidShieldedAddr(address)`
+  - RPC: `is_valid_shielded_address`
+  - returns `boolean`
+- `validateAddress(address)`
+  - RPC: `validate_address`
+  - returns:
+    - `isValid`
+    - `addressType`
+    - `reason`
+- `validateConsensusBranch(walletId)`
+  - RPC: `validate_consensus_branch`
+  - returns:
+    - `sdkBranchId`
+    - `serverBranchId`
+    - `isValid`
+    - `hasServerBranch`
+    - `hasSdkBranch`
+    - `isServerNewer`
+    - `isSdkNewer`
+    - `errorMessage`
+
+  Consensus branch IDs are opaque. Use `isValid` for compatibility; the two
+  `*Newer` fields remain for wire compatibility and are always `false`.
+
+### Addresses and balances
+
+Receive-address APIs are shielded and wallet-scoped:
+
+- `getCurrentReceiveAddress(walletId)`
+  - helper over `getCurrentAddress(walletId)`
+- `getCurrentAddress(walletId)`
+  - RPC: `current_receive_address`
+  - returns the current external receive address without rotating it
+- `getNextReceiveAddress(walletId)`
+  - helper over `getNextAddress(walletId)`
+- `getNextAddress(walletId)`
+  - RPC: `next_receive_address`
+  - rotates to and returns the next external receive address
+- `listAddresses(walletId)`
+  - RPC: `list_addresses`
+  - returns generated external receive addresses
+- `listAddressBalances(walletId, keyId?)`
+  - RPC: `list_address_balances`
+  - returns per-address balance entries
+
+These APIs return shielded receive addresses. Newly generated addresses use
+Sapling before Ironwood activation and Ironwood after activation. The current
+address can still be an older Sapling address until the wallet rotates, and
+`listAddresses(walletId)` can contain both Sapling and Ironwood receive
+addresses over time.
+
+- `getBalance(walletId)`
+  - RPC: `get_balance`
+  - returns decimal-string amount fields:
+    - `total`
+    - `spendable`
+    - `pending`
+- `getShieldedPoolBalances(walletId)`
+  - RPC: `get_shielded_pool_balances`
+  - returns:
+    - `sapling`
+    - `ironwood`
+- `getSpendabilityStatus(walletId)`
+  - RPC: `get_spendability_status`
+  - returns:
+    - `spendable`
+    - `rescanRequired`
+    - `targetHeight`
+    - `anchorHeight`
+    - `validatedAnchorHeight`
+    - `repairQueued`
+    - `reasonCode`
+
+### Transactions
+
+- `listTransactions(walletId, limit?)`
+  - RPC: `list_transactions`
+  - returns transaction array
+- `fetchTransactionMemo(walletId, txId, outputIndex?)`
+  - RPC: `fetch_transaction_memo`
+  - returns `string | null`
+- `getTransactionDetails(walletId, txId)`
+  - RPC: `get_transaction_details`
+  - returns transaction detail object or `null`
+- `exportPaymentDisclosures(walletId, txId)`
+  - RPC: `export_payment_disclosures`
+  - returns all recoverable payment disclosures for a sent transaction
+- `exportSaplingPaymentDisclosure(walletId, txId, outputIndex)`
+  - RPC: `export_sapling_payment_disclosure`
+  - returns one Sapling output disclosure string
+- `exportIronwoodPaymentDisclosure(walletId, txId, actionIndex)`
+  - RPC: `export_ironwood_payment_disclosure`
+  - returns one Ironwood action disclosure string
+- `verifyPaymentDisclosure(walletId, disclosure)`
+  - RPC: `verify_payment_disclosure`
+  - decrypts one Sapling or Ironwood disclosure using the wallet's configured lightwalletd endpoint
+
+`PaymentDisclosure` includes `disclosureType`, `txid`, `outputIndex`, `address`,
+`amount`, optional `memo`, and the shareable `disclosure` string.
+`verifyPaymentDisclosure` returns the same decrypted payment fields plus
+`memoHex`.
+- `getFeeInfo()`
+  - RPC: `get_fee_info`
+  - returns decimal-string fee fields plus `memoFeeMultiplier`:
+    - `defaultFee`
+    - `minFee`
+    - `maxFee`
+    - `feePerOutput`
+    - `memoFeeMultiplier`
+
+### Sync
+
+- `startSync(walletIdOrRequest, mode = 'Compact')`
+  - RPC: `start_sync`
+  - request fields:
+    - `walletId`
+    - `mode`
+  - returns acknowledgement object
+- `getSyncStatus(walletId)`
+  - RPC: `sync_status`
+  - returns:
+    - `localHeight`
+    - `targetHeight`
+    - `percent`
+    - `eta`
+    - `stage`
+    - `lastCheckpoint`
+    - `blocksPerSecond`
+    - `notesDecrypted`
+    - `lastBatchMs`
+- `cancelSync(walletId)`
+  - RPC: `cancel_sync`
+  - returns acknowledgement object
+- `rescan(walletIdOrRequest, fromHeight?)`
+  - RPC: `rescan`
+  - request fields:
+    - `walletId`
+    - `fromHeight`
+  - returns acknowledgement object
+
+Each wallet has its own sync state. Apps can run more than one wallet sync by
+creating synchronizers for different wallet IDs, subject to normal device,
+network, and lightwalletd resource limits. Compact block ranges are cached per
+endpoint, so later scans for another wallet on the same endpoint can reuse
+previously fetched ranges.
+
+### Send flow
+
+- `buildTransaction(walletIdOrRequest, outputs?, fee?)`
+  - RPC: `build_tx`
+  - request fields:
+    - `walletId`
+    - `outputs`
+    - optional `fee`
+  - each output contains:
+    - `addr`
+    - `amount`
+    - optional `memo`
+  - returns pending transaction object
+- `signTransaction(walletId, pending)`
+  - RPC: `sign_tx`
+  - returns signed transaction object
+- `broadcastTransaction(signed)`
+  - RPC: `broadcast_tx`
+  - returns transaction id string
+- `send(walletId, outputsOrOutput, fee?)`
+  - helper over `buildTransaction()`, `signTransaction()`, and `broadcastTransaction()`
+  - returns transaction id string
+
+`buildTransaction()`, `signTransaction()`, and `send()` are wallet-scoped.
+`broadcastTransaction(signed)` only receives the signed transaction payload; if
+endpoint configuration is needed during broadcast, the service uses the active
+wallet.
+
+Change-address selection is automatic. Sapling-only change uses legacy
+same-address change before Ironwood activation and Sapling internal change after
+activation; Ironwood spends or outputs use Ironwood internal change.
+
+### Viewing keys and watch-only
+
+- `exportSaplingViewingKey(walletId)`
+  - RPC: `export_sapling_viewing_key`
+  - returns Sapling viewing key string
+- `exportIronwoodViewingKey(walletId)`
+  - RPC: `export_ironwood_viewing_key`
+  - returns Ironwood viewing key string
+- `importSaplingViewingKeyAsWatchOnly(requestOrName, saplingViewingKey?, birthdayHeight?)`
+  - RPC: `import_sapling_viewing_key_as_watch_only`
+  - returns wallet id string
+- `getWatchOnlyCapabilities(walletId)`
+  - RPC: `get_watch_only_capabilities`
+  - returns capability object
+
+### Advanced key management
+
+These methods live under `sdk.advancedKeyManagement`.
+
+- `listKeyGroups(walletId)`
+  - RPC: `list_key_groups`
+  - returns key group array
+- `exportKeyGroupKeys(walletId, keyId)`
+  - RPC: `export_key_group_keys`
+  - returns:
+    - `keyId`
+    - `saplingViewingKey`
+    - `ironwoodViewingKey`
+    - `saplingSpendingKey`
+    - `ironwoodSpendingKey`
+- `importSpendingKey(requestOrWalletId, birthdayHeight?, saplingSpendingKey?, ironwoodSpendingKey?)`
+  - RPC: `import_spending_key`
+  - returns key id number
+- `exportSeed(walletId, mnemonicLanguage?)`
+  - RPC: `export_seed_raw`
+  - returns mnemonic string
+
+### Mnemonic language values
+
+Where `mnemonicLanguage` is supported, the accepted values are:
+
+- `english`
+- `chinese_simplified`
+- `chinese_traditional`
+- `french`
+- `italian`
+- `japanese`
+- `korean`
+- `spanish`
+
+Behavior:
+
+- if omitted during `restoreWallet()` or `validateMnemonic()`, the backend attempts autodetection
+- if omitted during `exportSeed()`, the wallet's original stored mnemonic language is used
+- if provided during export, the same seed entropy is re-rendered in the requested language
+
+### Synchronizer
+
+Create a synchronizer with:
+
+- `createSynchronizer(walletId, config?)`
+
+Public state:
+
+- `status`
+- `progress`
+- `syncStatus`
+- `latestBirthdayHeight`
+- `balance`
+- `transactions`
+- `lastError`
+
+Methods:
+
+- `currentSnapshot()`
+- `isRunning()`
+- `isSyncing()`
+- `isComplete()`
+- `start()`
+- `stop()`
+- `refresh()`
+- `close()`
+- `subscribe(callbacks?)`
+
+`stop()` and `close()` both cancel backend sync for the wallet. In React Native code,
+`await synchronizer.close()` instead of treating `close()` as a local timer-only cleanup step.
+
+A synchronizer is scoped to one wallet ID. Create one synchronizer per wallet
+when running multi-wallet sync.
+
+Callback hooks:
+
+- `onStatusChanged`
+- `onUpdate`
+- `onError`
+
+## Install in a React Native app
+
+Install the package in the app and run CocoaPods as usual:
+
+```bash
+npm install react-native-pirate-wallet
+cd ios && pod install
+```
+
+On Android, npm installs the exact-version
+`react-native-pirate-wallet-android` companion automatically. The wrapper
+autolinks as a standard React Native native module and adds the companion's JNI
+libraries to the build.
+
+On iOS, the podspec links the vendored `PirateWalletNative.xcframework`.

package/android/build.gradle

@@ -0,0 +1,82 @@
+buildscript {
+  def kotlinVersion = rootProject.ext.has('kotlinVersion')
+    ? rootProject.ext.get('kotlinVersion')
+    : '2.2.21'
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath 'com.android.tools.build:gradle:8.13.2'
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlinVersion}"
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+def androidBinaryPackages = [
+  'react-native-pirate-wallet-android',
+  'react-native-pirate-wallet-android-x86_64',
+]
+def androidJniLibsDirs = androidBinaryPackages.collect { packageName ->
+  def candidates = [
+    file("../node_modules/${packageName}/android/src/main/jniLibs"),
+    file("../../${packageName}/android/src/main/jniLibs"),
+  ]
+  def jniLibsDir = candidates.find { it.isDirectory() }
+  if (jniLibsDir == null) {
+    throw new GradleException(
+      "${packageName} must be installed before building Android"
+    )
+  }
+  jniLibsDir
+}
+
+android {
+  namespace "com.pirate.wallet.reactnative"
+  compileSdkVersion safeExtGet('compileSdkVersion', 36)
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 24)
+    targetSdkVersion safeExtGet('targetSdkVersion', 36)
+    consumerProguardFiles 'consumer-rules.pro'
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = '17'
+  }
+
+  sourceSets {
+    main {
+      jniLibs.srcDirs androidJniLibsDirs
+    }
+  }
+
+  lintOptions {
+    abortOnError false
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+  maven {
+    url("${rootProject.projectDir}/../node_modules/react-native/android")
+  }
+}
+
+dependencies {
+  implementation 'com.facebook.react:react-native:+'
+}

package/android/consumer-rules.pro

@@ -0,0 +1 @@
+

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest />