@bennyblader/ddk-rn 0.4.0 → 1.0.0-rc1

package/README.md

@@ -24,6 +24,8 @@ Prebuilt platform coverage:
 
 The Intel Mac simulator (`x86_64`) is not included.
 
+Prereleases publish to the `next` dist-tag: `npm install @bennyblader/ddk-rn@next`.
+
 ## Quick Start
 
 ```typescript
@@ -32,18 +34,70 @@ import { version, createFundTxLockingScript } from '@bennyblader/ddk-rn';
 console.log(`DDK Version: ${version()}`);
 ```
 
-For complete API documentation, see the [main README](../README.md#api-reference).
+### The contract API
+
+The whole DLC lifecycle runs on device, with no contract store — every
+transaction is rebuilt from the offer/accept/sign wire messages when it is
+needed, and funding secret keys stay inside Rust behind a `ContractKeyProvider`.
+
+```typescript
+import {
+  ContractKeyProvider,
+  chainHashFromNetwork,
+  createOffer,
+  acceptOffer,
+  signAccept,
+  finalizeSign,
+  signContractCet,
+} from '@bennyblader/ddk-rn';
+
+const keys = ContractKeyProvider.fromMnemonic(MNEMONIC, undefined, 'regtest');
+const temporaryContractId = new Uint8Array(32).fill(1).buffer;
+
+const offer = createOffer({
+  chainHash: chainHashFromNetwork('regtest'),
+  temporaryContractId,
+  contractInfo: CONTRACT_INFO,
+  offerCollateralSats: 50_000n,
+  party: {
+    fundingPubkey: keys.fundingPubkey(temporaryContractId),
+    fundingInputs: [FUNDING_INPUT],
+    payoutSpk: SPK,
+    changeSpk: SPK,
+  },
+  feeRatePerVb: 2n,
+  cetLocktime: 0,
+  refundLocktime: 1_700_000_000,
+  contractFlags: 0,
+});
+// …acceptOffer → sign the funding PSBT → signAccept → finalizeSign →
+//   signContractCet / signContractRefund
+```
+
+Bytes cross the JSI boundary as `ArrayBuffer` (`ddk-ts` uses `Buffer`).
+
+`example/src/App.tsx` runs the complete flow on device — offline, deterministic,
+and asserted by the Maestro E2E.
+
+For complete API documentation, see the [main README](../README.md#-the-contract-api).
 
 ## Development
 
 ### Prerequisites
 
-- Node.js >= 14
+- Node.js >= 20
 - Rust >= 1.70
 - pnpm
-- UniFFI React Native: `npm install -g uniffi-bindgen-react-native`
+- UniFFI React Native, installed globally at the version pinned in
+  `package.json`: `pnpm add -g uniffi-bindgen-react-native@<version>`
 - iOS: Xcode 14+, CocoaPods
-- Android: Android Studio, NDK
+- Android: Android Studio, NDK 27.1.12297006
+
+> The `uniffi` crate, this package's `uniffi-bindgen-react-native` dependency,
+> and the globally installed binary must all be the same release — the `just`
+> recipes call the binary on `$PATH`, not the one in `node_modules`. A skew shows
+> up as TypeScript errors like "Expected 2 arguments, but got 1" on every
+> generated `.lower()` call.
 
 ### Building from Source
 
@@ -51,30 +105,26 @@ For complete API documentation, see the [main README](../README.md#api-reference
 # Install dependencies
 pnpm install
 
-# Generate all bindings and build native libraries
-just uniffi
-
-# Note: After building, manually fix the include path in cpp/bennyblader-ddk-rn.cpp
-# Change: #include "/ddk_ffi.hpp"
-# To: #include "ddk_ffi.hpp"
+# Generate all bindings and build the native libraries
+just build
 ```
 
 ### Just Commands
 
 ```bash
-# Complete build (generates bindings + builds iOS/Android)
-just uniffi
+# JSI + TurboModule bindings, the iOS XCFramework, and ddk-ts
+just build
 
-# Generate JSI bindings only
+# Generate JSI bindings only (TypeScript + C++)
 just uniffi-jsi
 
 # Generate TurboModule specifications
 just uniffi-turbo
 
-# Build iOS libraries
+# Build the iOS XCFramework (release, stripped)
 just build-ios
 
-# Build Android libraries
+# Build the Android JNI libraries (needs the NDK)
 just build-android
 
 # Setup example app
@@ -86,51 +136,101 @@ just example-ios
 # Android example build
 just example-android
 
+# Report the size of every binary destined for the npm package
+just binary-sizes
+
 # Clean all generated files
 just clean
-
-# Release new version
-just release
-
-# Create release archives
-just release-archives
 ```
 
+> Adding a new `#[uniffi::export]` needs `just build-ios`, not just
+> `just uniffi-jsi`. `uniffi-jsi` regenerates the TypeScript and C++, but the C++
+> calls into the XCFramework, which only `build-ios` rebuilds — skip it and the
+> app fails at link with `Undefined symbols … _uniffi_ddk_ffi_fn_func_<name>`.
+> Nothing earlier in the chain catches this.
+
 ### Project Structure
 
 ```
 ddk-rn/
 ├── src/                # Generated TypeScript bindings
 │   ├── index.tsx       # Main entry point (generated)
-│   └── ddk_ffi*.ts     # Type definitions (generated)
+│   ├── ddk_ffi.ts      # The API consumers import (generated)
+│   ├── ddk_ffi-ffi.ts  # Native JSI symbol declarations (generated)
+│   └── __tests__/      # Hand-written — the only non-generated code in src/
 ├── cpp/                # Generated C++ JSI bindings
 │   ├── ddk_ffi.hpp     # C++ header (generated)
 │   ├── ddk_ffi.cpp     # C++ implementation (generated)
 │   └── *.cpp/.h        # TurboModule files (generated)
 ├── ios/                # iOS native module
-│   ├── DdkRn.xcframework/ # iOS framework (generated)
-│   └── *.swift/.m      # iOS bridge code
+│   ├── DdkRn.xcframework/ # Prebuilt iOS framework (generated, shipped)
+│   └── *.h/.mm         # iOS bridge code
 ├── android/            # Android native module
 │   └── src/main/
 │       ├── java/       # Kotlin/Java bridge code
-│       └── jniLibs/    # Native libraries (generated)
-├── example/            # Example React Native app
-├── scripts/            # Build and release scripts
+│       └── jniLibs/    # Prebuilt native libraries (generated, shipped)
+├── example/            # Example React Native app + Maestro flows
+├── patches/            # pnpm patch for an unreleased ubrn fix
+├── scripts/            # Package verification
 └── ubrn.config.yaml    # UniFFI React Native configuration
 ```
 
+Everything in `src/` except `src/__tests__/` is generated — don't hand-edit it,
+and don't "fix" lint errors inside it (those files are in `eslintIgnore` for
+exactly that reason).
+
+### Testing
+
+```bash
+pnpm test       # jest
+pnpm typecheck  # tsc
+pnpm lint       # eslint
+```
+
+`src/__tests__/contractBindings.test.js` is a binding-surface test: the JSI
+bindings can't execute under Node, so it asserts instead that generation was
+complete — every function, record, and constructor present in both the
+TypeScript surface and the native symbol layer. It catches the classic
+regression where `ddk-ffi` changed but `ddk-rn` wasn't regenerated. Runtime
+behavior is covered by the shared Rust (`ddk-ffi` unit tests and the `ddk-ts`
+suite exercise the same functions).
+
+### End-to-end, on a device
+
+CI installs the example app on an iOS simulator and an Android emulator and
+drives the full contract flow with Maestro. It is the only layer that exercises
+the real JSI bindings, and the only one that catches an app that never finishes
+launching.
+
+| command | needs | time |
+|---|---|---|
+| `just e2e-flows` | nothing — no device, no app | ~15s |
+| `just e2e-ios-test` | the app already installed | ~10s |
+| `just e2e-ios` | full: build + install + run | ~5-10m |
+
+Android needs a one-time `just e2e-android-setup` (~1.5GB) to create the
+emulator and AVD, then `just e2e-android`.
+
+While editing a flow, stay in `e2e-ios-test`; only rebuild when the app itself
+changes (JS, Rust, or the generated bindings).
+
 ### Platform Support
 
-| Platform      | Architecture | Status       |
-| ------------- | ------------ | ------------ |
-| iOS           | ARM64        | ✅ Supported |
-| iOS Simulator | x64/ARM64    | ✅ Supported |
-| Android       | ARM64-v8a    | ✅ Supported |
-| Android       | ARMv7        | ✅ Supported |
-| Android       | x86_64       | ✅ Supported |
+| Platform      | Architecture     | Status          |
+| ------------- | ---------------- | --------------- |
+| iOS           | ARM64            | ✅ Supported    |
+| iOS Simulator | ARM64            | ✅ Supported    |
+| iOS Simulator | x64 (Intel Mac)  | ❌ Not included |
+| Android       | ARM64-v8a        | ✅ Supported    |
+| Android       | ARMv7            | ✅ Supported    |
+| Android       | x86 / x86_64     | ✅ Supported    |
 
 ### Building the Example App
 
+The example is pinned to React Native 0.80 / React 19.1 — the release these
+bindings are supported against, so the E2E exercises the toolchain consuming
+apps actually build with.
+
 #### iOS
 
 ```bash
@@ -155,35 +255,60 @@ npx react-native run-android
 
 ### Release Process
 
-To release a new version:
+`ddk-ts` and `ddk-rn` are versioned and released together, from the repo root:
 
 ```bash
-just release
+just release 0.5.0
 ```
 
 This will:
 
-1. Build all native bindings
-2. Run tests
-3. Update version
-4. Create release commit and tag
-5. Push to GitHub
-6. Publish to npm
+1. Check the working directory is clean
+2. Set the version in `ddk-ts/package.json`, `ddk-rn/package.json` and `ddk-ffi/Cargo.toml`
+3. Commit, tag as `v0.5.0` and push
+
+Publishing happens in CI — pushing the tag is what publishes. The iOS
+XCFramework is built on `macos-latest`, the Android JNI libraries on
+`ubuntu-latest` with the NDK, and a final job assembles both and verifies the
+binaries are in the tarball before publishing. Nothing is published from a
+developer machine; `prepublishOnly` refuses a hand-run `npm publish` that would
+ship without binaries.
+
+Update the `[Unreleased]` section of [CHANGELOG.md](./CHANGELOG.md) **before**
+releasing — the release script refuses a dirty tree, so it can't be part of the
+release commit.
 
 ### API Compatibility
 
-The React Native bindings maintain 100% API compatibility with the UniFFI definitions. All functions are generated directly from the UDL file ensuring consistency across platforms.
+All bindings are generated from the compiled `ddk-ffi` library, whose Rust
+source — annotated with UniFFI proc-macros, with no `.udl` file — is the single
+source of truth for the interface.
 
-### Known Issues
+`@bennyblader/ddk-ts` is hand-written NAPI over the same crates and is kept in
+parity by CI. Two differences to know: bytes are `ArrayBuffer` here and `Buffer`
+there, and a dozen transaction operations are methods on a record here
+(`TxOutput.isDust`, `Transaction.signCet`, …) but free functions there. See the
+[comparison table](../README.md#where-the-two-packages-differ).
 
-1. **Manual Include Path Fix**: After running `just uniffi`, you must manually fix the include path in `cpp/bennyblader-ddk-rn.cpp`:
-   - Change: `#include "/ddk_ffi.hpp"`
-   - To: `#include "ddk_ffi.hpp"`
+### Known Issues
 
-2. **New Architecture**: The library requires React Native's new architecture to be enabled:
+1. **New Architecture**: The library requires React Native's new architecture to be enabled:
    - iOS: Set `RCT_NEW_ARCH_ENABLED=1`
    - Android: Set `newArchEnabled=true` in `gradle.properties`
 
+2. **Android C++ builds need an unreleased ubrn fix.** The generated
+   `android/CMakeLists.txt` resolves the ubrn package with
+   `require.resolve('uniffi-bindgen-react-native/package.json')`, which throws
+   `ERR_PACKAGE_PATH_NOT_EXPORTED` because ubrn's `exports` map doesn't expose
+   that subpath. The include dir silently becomes `/cpp/includes` and the build
+   dies with `'UniffiCallInvoker.h' file not found`. This repo patches it
+   (`patches/uniffi-bindgen-react-native@0.31.0-3.patch`, applied by
+   `pnpm install`), but a pnpm patch only applies to this repo — building an
+   Android app against the published package hits the original error until ubrn
+   ships the fix ([#404](https://github.com/jhugman/uniffi-bindgen-react-native/issues/404),
+   fixed on `main`, release tracked in
+   [#421](https://github.com/jhugman/uniffi-bindgen-react-native/issues/421)).
+
 ## Troubleshooting
 
 ### iOS Build Issues
@@ -212,7 +337,17 @@ If bindings are missing, regenerate them:
 
 ```bash
 just clean
-just uniffi
+just build
+```
+
+### A modified `android/build.gradle` after building
+
+`just build-android <abi>` narrows `abiFilters` to the ABIs you passed and wipes
+`jniLibs/` for the rest. Never commit that — a single-ABI `build.gradle` ships an
+app that only runs on one architecture:
+
+```bash
+git checkout android/build.gradle
 ```
 
 ## License