Reimplement Pirate Chain plugin over react-native-pirate-wallet

[j0ntz]

Technical Design Document

piratechain-sdk-v115-reconcile.md, committed on this branch. It holds the design, every decision with its rejected alternatives, the phase history, and the test evidence. Read it instead of a long description here.

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Description

Asana: https://app.asana.com/0/1215088146871429/1214721783909451

Reimplements the Pirate Chain plugin over react-native-pirate-wallet (unified wallet v1.1.6, npm 0.3.0), the Pirate team's replacement for the react-native-piratechain module Edge wrote. In the old module the Swift and Rust layers each opened the wallet's SQLite database and the app crashed when they overlapped, which is why unrelated work has to set piratechain: false in the GUI's corePlugins.ts. The new SDK keeps all database access in Rust, and this branch retires that workaround.

The plugin's public shape and the engine's transaction mapping are unchanged. What is new:

• One device-scoped SDK wallet registry holds every ARRR wallet, keyed by wallet-id alias and unlocked by a random per-device passphrase kept in the plugin's local storage.
• Sync comes from the SDK's polling synchronizer and history from list_transactions. Amounts cross the wire as decimal strings, and sends go through the SDK's send().
• Each wallet is pointed at Edge's own lightwalletd node with set_lightd_endpoint. Without it a wallet scans against the SDK's baked-in default, which now refuses connections outright, and the app sits at 0% sync with no error anywhere.
• getLatestNetworkHeight takes the chain tip from a registered wallet or from test_node, falling back to the create-and-delete probe only when the registry is empty. Running that probe while a synchronizer is live panics the native service and aborts the app.

Paired with EdgeApp/edge-react-gui#6021, which swaps the GUI dependency and has to land after this one publishes.

Verified on the iOS simulator: a funded ARRR send reached the transaction-success scene (txid 8d2e25d0e624cf714057b65311347a8a5d21cafbbae8f579e714fb979e94a579, 2.083 seconds from build to broadcast), both wallets sync, a resync ran at about 47,700 blocks/sec, and the mocha suite is 490 passing. Section 7 of the doc has the full numbers and what stayed uncovered.

---

Note

High Risk
This is a full native SDK and wallet-storage swap for ARRR—sync, spend, registry passphrase handling, and lightwalletd routing all change—and incorrect endpoint or registry behavior can strand wallets at 0% sync or block spends; Ironwood readiness depends on pinning v1.1.6.

Overview
Replaces react-native-piratechain with react-native-pirate-wallet (unified wallet v1.1.6, peer ^0.3.0) and rewrites the native IO bridge and engine around the SDK’s encrypted wallet registry and polling synchronizer.

Device-scoped registry: One configureAccountStorage namespace (edge-pirate-device) holds every ARRR wallet keyed by wallet-id alias; a random 32-byte passphrase is minted on the core side (piratechainDeviceStorage.ts) and passed to the bridge via setDevicePassphrase. Multiple wallets can sync concurrently on a shared block cache without namespace switching.

Sync and history: Transaction history no longer uses block-range paging in otherData; the engine processes the SDK’s full list_transactions list with a per-txid height cache. Balances and txs use string amounts end-to-end; sends go through walletSdk.send() instead of raw build/sign/broadcast invoke. A one-time getStatus() backstop avoids staying stuck at STOPPED if SYNCED fires before subscriptions attach.

lightwalletd: Each wallet gets set_lightd_endpoint with the plugin’s lightwalletdUrl (http://lightd1.pirate.black:9067 plain gRPC), because the SDK ignores plugin networkInfo and its baked-in default node is unreachable or non-serving.

Adds local rnPirateWallet.d.ts typings and a long design doc; package-lock drops the old piratechain dev dependency.

^{Reviewed by Cursor Bugbot for commit 25992e1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[j0ntz]

Simulator-tested update (force-pushed as part of the single commit):

• App passphrase unlock: the SDK's SQLCipher store rejects every wallet call with Security error: App is locked until set_app_passphrase/unlock_app runs. The io bridge now unlocks (or provisions) the passphrase store before any wallet operation. Verified on the iOS sim: registry restore, viewing-key derivation, and zs1… receive address all work.
• Direct tunnel: the SDK transports through Tor by default, which never bootstraps inside Edge — sync sat at stage: Headers, target_height: 0 forever. The bridge now issues set_tunnel {mode: Direct} after unlock, matching every other Edge plugin's connectivity. Verified the sync config flips to transport: Direct against http://64.23.167.130:9067 (server healthy; tip 3,990,043 via grpcurl).

Upstream blocker found while testing: block sync still cannot progress through this binding. pirate-ffi-native builds a throwaway current-thread tokio runtime per invoke, and sync_control::start_sync spawns the sync engine onto it — the task is destroyed when the call returns. The Flutter app works only because flutter_rust_bridge keeps a persistent runtime; the RN/iOS/Android SDK bindings all share this defect, and the bounded start_background_sync API is not exposed through the JSON dispatcher. Needs a Pirate-team fix (persistent global runtime in pirate-ffi-native, or expose start_background_sync via invoke). Until then balances/sends can't be exercised end-to-end.

[j0ntz]

End-to-end sync + send verified on the iOS simulator (with a locally rebuilt pirate core carrying the one-line persistent-runtime fix):

• Funded wallet (254.547 ARRR) restored from its Edge mnemonic + birthday and fully scanned ~940k blocks to chain tip; SDK balance matched Edge's cached pre-upgrade balance to the arrrtoshi.
• Sent 3.261 ARRR wallet-to-wallet in the same account: txid b44367658e7c92cd916eccbdee3dc8f6861a48985683037040a8ead2035c9881, broadcast accepted by http://64.23.167.130:9067.

Two more findings, both addressed in the latest force-push:

1. Wrapper send bug (upstream): sdk.send()/signTransaction() camelize the build_tx result and feed it back into sign_tx, which rejects it (Invalid request JSON: missing field 'total_amount'). The bridge now drives build_tx → sign_tx → broadcast_tx over the raw invoke channel so the pending/signed payloads round-trip untouched.
2. Runtime defect confirmed + fix validated: rebuilding libpirate_ffi_native with a persistent global tokio runtime in WalletService::execute_blocking (instead of a per-call current-thread runtime) makes foreground sync work through the json-invoke bindings. That's the patch to upstream to the Pirate team — without it the stock release binaries cannot sync outside their Flutter app.

[peachbits]

Two non-blocking suggestions on the new react-native-pirate-wallet integration, both at the native-bridge boundary. The plugin reimplementation reads cleanly otherwise.

[j0ntz]

📸 Test evidence: e2e ARRR send (iOS sim)

arrr my pirate2 synced

arrr send dest zaddr

arrr send confirm

arrr send success

arrr send txid

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

📸 Test evidence

arrr synced

arrr send ready

arrr sync stalled

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

📸 Test evidence: react-native-pirate-wallet 0.3.0 (unified wallet v1.1.6), funded ARRR send

arrr synced 0.3.0

arrr send ready

arrr send success

arrr balance after send

Captured by the agent's in-app test run (build-and-test).

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 70ea0d9. Configure here.}