[j0ntz]

Technical Design Document

piratechain-unified-wallet-sdk.md

, committed on the plugin branch. It holds the design and the test evidence for both PRs in this pair. Read it instead of a long description here.

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

EdgeApp/edge-currency-accountbased#1055

Requirements

If you have made any visual changes to the GUI. Make sure you have:

• Tested on iOS device
• Tested on Android device
• Tested on small-screen device (iPod Touch)
• Tested on large-screen device (tablet)

Description

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

Swaps react-native-piratechain for react-native-pirate-wallet@0.3.4 (unified wallet SDK). The reimplemented plugin in EdgeApp/edge-currency-accountbased#1055 consumes it through the existing makePiratechainIo nativeIo bridge, so this side is the dependency swap, four testIDs on the send scene's address tile (whose icon buttons an automated drive cannot otherwise select by text), and one send-scene error mapping.

The error mapping: ErrorCard shows a specific message only for an I18nError and otherwise falls back to "An unexpected error occurred. Please check your network connection and try again later." A wallet whose balance exists but is not spendable yet reports that as PendingFundsError, which the plugin now throws for the Pirate Chain spend-anchor window and monero already throws for unconfirmed funds. Both of SendScene2's catches turn it into an I18nError that keeps the plugin's own message when it set one (the Pirate Chain engine names syncing, rescanning or witness repair from the SDK's reasonCode) and otherwise shows "These funds are not spendable yet. Wait for the wallet to finish syncing, then try again." Ethereum's pending-transaction case carries the same error type with a sentinel message and keeps its own warning card, so it is matched first and left alone.

The wrapper tarball carries only JS and the ObjC/Swift/Kotlin bridge. Its native binaries arrive as five optionalDependencies pinned to the wrapper version: two Android packages, one iOS device package, and one package per iOS simulator architecture, which 0.3.2 split apart so a developer pulls only what their machine runs. The iOS three are marked os: ["darwin"], so Linux CI skips them; the two Android packages carry no os or cpu gate, so every runner and every Mac downloads both. Footprint: about 850MB of node_modules on a Mac (device 191MB, each simulator slice about 190MB, Android 180MB plus 101MB) against 79MB for react-native-piratechain@0.6.1. The xcframework assembly runs from the package's own podspec at pod install (top-level Ruby, --force, raises if the framework is missing), so scripts/prepare.sh no longer calls it; deleting the assembled framework and running pod install reproduces ios-arm64 (arm64) and ios-arm64_x86_64-simulator (x86_64 + arm64). The podspec links the Security framework for the keychain-backed registry credential the plugin now uses.

Landing order: #1055 has to publish first. Published edge-currency-accountbased@4.87.0 imports the module this branch removes, so a build without #1055 linked in fails at "Bundle React Native code and images".

Earlier revisions of this description carried the arm64 Debug link failure as a shipping blocker and the ARRR broadcast timeout as an open SDK defect. Both are settled and written up in the doc: the link failure is Debug-only, with a local Release device build and a Jenkins cheese build of this branch both green, and the broadcast takes 2.083 seconds.

The new copy was captured on the simulator against a real trigger, not a forced one: the SDK rejected a funded ARRR broadcast with ERR_WITNESS_REPAIR_QUEUED, and the scene rendered the wait-and-retry message where it had shown the network-error card. Screenshots are in a comment below.

Tested on the iOS simulator with #1055 linked in via updot: the app builds and launches with the 0.3.4 binaries, the plugin loads, a wallet restored from the account archive synced through the new keychain-backed registry, and a funded ARRR send reached the transaction-success scene through a signing session (txid 93f42a33af4161d697277f050da1c65c1dbf267c2aafdeaa1329ba063f64fbcb; the 0.3.2 round's send was 239ab8743afbed4f8047ed4e0b05d2aa3e39ebfa7ab9824ddfa52c72c47c4205).

The previous revision of this paragraph reported ARRR scan throughput collapsing to a few blocks per second and blamed 0.3.2. A controlled cold-sync A/B on this round found otherwise: 0.3.2 reaches the chain tip in 95 seconds against lightwalletd2.cryptoforge.cc and needs half an hour against lightd1.pirate.black, where 0.3.0 takes 72 seconds. The regression is an interaction with that one endpoint, not the SDK, so the bump stands and #1055 moves the endpoint. Section 7 of the doc has the matrix.

---

Note

Medium Risk
Replaces ARRR’s native wallet stack and adjusts send broadcast/error handling; correctness depends on the linked currency plugin and new prebuilt native binaries.

Overview
Swaps Pirate Chain’s native dependency from react-native-piratechain to react-native-pirate-wallet@0.3.4, including npm lockfiles and iOS CocoaPods (OpenSSL/SQLite/SwiftProtobuf bumps follow the new pod). This pairs with the account-based plugin that consumes the unified wallet SDK; without that plugin release, the app won’t resolve the old module at bundle time.

Send flow: When a wallet reports PendingFundsError (not-yet-spendable balance—common for ARRR spend-anchor / sync states and similar Monero cases), SendScene2 now surfaces the plugin message or a dedicated “funds not spendable yet” string instead of the generic network error card. On broadcast refusal before submission, the send slider re-arms (broadcast lock cleared); Ethereum’s existing “Unexpected pending transactions” path is unchanged.

Automation: Adds testIDs on the send address tile actions (enter, scan, paste, myself) for Maestro. CHANGELOG documents the SDK swap and the send error fix.

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

Test evidence

d774d70 test: add missing testIDs for maestro selectors	arrr synced 0.3.0	arrr send ready	arrr send success
	arrr balance after send	arrr synced 0.3.2 tls pool	arrr send success 0.3.2 tls
	arrr txid 0.3.2 tls
5a0ef14 Name the not-yet-spendable send error 🪓 forced the bridge's getSpendability in the updot-baked plugin copy to return spendable:false with reasonCode ERR_WITNESS_REPAIR_QUEUED (frames 04, 05) then ERR_SYNC_FINALIZING (frame 06); reverted, git status clean.	before generic error	not spendable error	keychain registry syncing
	transaction success	txid	max fills spendable balance
	send armed	transaction success	🪓 max refused witness repair
	🪓 not spendable witness repair	🪓 not spendable sync finalizing	send armed fresh registry
	transaction success fresh registry

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	react-native-pirate-wallet@​0.3.4

View full report

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[cursor]

Stale Bugbot comment from a previous run.

[claude]

Claude Code Review

Claude Code Review is paused for this repository. To reconnect it, an admin of this repository's GitHub organization (or the account owner, for personal repositories) who can also manage your Claude organization's Code Review settings needs to re-link GitHub in Code Review settings. This is a one-time step.

_{Tip: disable this comment in your organization's Code Review settings.}

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[peachbits]

Reviewed the native-dependency swap and the send-path changes. The prepare.sh addition is the main one — the script it calls is clean, but the package's podspec already runs it with --force at pod install time, so the line looks redundant. Skipping the edge-currency-accountbased pin, already covered above.

[j0ntz]

Addressed all three threads: the prepare.sh assembly line is removed (the podspec's --force path verified by deleting the framework and running pod install), the footprint is stated in the description, and the send scene keeps the plugin's message with the localized line as the fallback.

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Low adoption: npm react-native-pirate-wallet-android-x86_64 Location: Package overview From: package-lock.json → npm/react-native-pirate-wallet@0.3.4 → npm/react-native-pirate-wallet-android-x86_64@0.3.4 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/react-native-pirate-wallet-android-x86_64@0.3.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Low adoption: npm react-native-pirate-wallet-android Location: Package overview From: package-lock.json → npm/react-native-pirate-wallet@0.3.4 → npm/react-native-pirate-wallet-android@0.3.4 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/react-native-pirate-wallet-android@0.3.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Low adoption: npm react-native-pirate-wallet-ios-device Location: Package overview From: package-lock.json → npm/react-native-pirate-wallet@0.3.4 → npm/react-native-pirate-wallet-ios-device@0.3.4 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/react-native-pirate-wallet-ios-device@0.3.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Low adoption: npm react-native-pirate-wallet-ios-simulator-arm64 Location: Package overview From: package-lock.json → npm/react-native-pirate-wallet@0.3.4 → npm/react-native-pirate-wallet-ios-simulator-arm64@0.3.4 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/react-native-pirate-wallet-ios-simulator-arm64@0.3.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Low adoption: npm react-native-pirate-wallet-ios-simulator-x86_64 Location: Package overview From: package-lock.json → npm/react-native-pirate-wallet@0.3.4 → npm/react-native-pirate-wallet-ios-simulator-x86_64@0.3.4 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/react-native-pirate-wallet-ios-simulator-x86_64@0.3.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Low adoption: npm react-native-pirate-wallet Location: Package overview From: package-lock.json → npm/react-native-pirate-wallet@0.3.4 ℹ Read more on: This package | This alert | What are unpopular packages? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Unpopular packages may have less maintenance and contain other problems. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/react-native-pirate-wallet@0.3.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default 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 8699fb7. Configure here.}

[cursor]

🔒 Agentic Security Review

Severity: MEDIUM

Description: ARRR native spend code is now linked from PirateNetwork npm prebuilt companions (react-native-pirate-wallet@0.3.4 plus optional android/ios tarballs) instead of the Edge-published react-native-piratechain wrapper. Edge release/CI only enforces lockfile integrity and does not verify npm SLSA/OIDC provenance or rebuild those JNI/xcframework blobs.

Impact: This PR adds a new in-process trust root for wallet-key material. A hostile or substituted libpirate_ffi_native.so / PirateWalletNative.xcframework in those tarballs is autolinked into the Edge Android/iOS binary and runs with the app process, so it can steal or redirect Pirate Chain keys and signed transactions and can also reach other secrets in the same process. Sibling privacy-coin modules (react-native-zcash, react-native-monero) remain Edge-published; this swap drops that Edge-owned native packaging gate for ARRR.

Remediation: Keep the exact lockfile pins. Add an Edge-enforced gate before merge/release: npm provenance verify that the six 0.3.4 attestations bind to PirateNetwork/Pirate-Unified-Light-Wallet and the expected workflow/tag, or pin GitHub-release tarball hashes from that project's signature/SBOM, or vendor/rebuild the native slices under an Edge-controlled package as with react-native-zcash/react-native-monero.