Harden stable SDK parity and release contracts

Author: zeusbuilds

README.md

@@ -15,10 +15,14 @@ The current source/static parity pass compares this repository with:
 - `@utexo/rgb-sdk-core` `1.0.0-beta.7`
 - RGB Lightning Node `0.10.0-beta.3`
 
-The source baseline now targets those exact versions, and the pinned native
-artifact remains unchanged from the RN package. The SDK still has confirmed
-packaging, code-quality, supply-chain, and exact runtime evidence gaps, so
-baseline alignment must not be mistaken for release readiness.
+The source baseline targets those exact versions, and the pinned native
+artifact remains unchanged from the RN package. Repository-owned API, model,
+lifecycle, code-quality, and packaging findings are closed; the final source
+still requires its exact clean-candidate local runtime rerun. Production
+remains blocked by `PKG-006`: the upstream
+native artifacts do not yet have the required verified signatures, trusted-key
+policy, and reproducible-build/source attestations. Baseline alignment and
+internal-beta evidence must not be mistaken for production readiness.
 
 The authoritative verdict and issue ledger are in the
 [Release Readiness Tracker](doc/RELEASE_READINESS_TRACKER.md). Do not infer
@@ -81,7 +85,7 @@ await wallet.unlock(
     bitcoindRpcHost: '127.0.0.1',
     bitcoindRpcPort: 18444,
     indexerUrl: '127.0.0.1:50002',
-    proxyEndpoint: 'rpc://127.0.0.1:3003/json-rpc',
+    proxyEndpoint: 'rpc://127.0.0.1:3013/json-rpc',
   ),
 );
 ```
@@ -95,7 +99,7 @@ toolchain and must fail when required local gates are skipped.
 flutter --version
 dart --version
 flutter pub get
-dart format --output=none --set-exit-if-changed lib test pigeons tool
+dart format --output=none --set-exit-if-changed lib test example/integration_test pigeons tool
 dart run tool/validate_release_governance.dart
 dart run tool/validate_codebase_hardening.dart
 dart run tool/validate_public_api_docs.dart

android/src/main/kotlin/com/utexo/rgb_sdk_flutter/RgbSdkFlutterPlugin.kt

@@ -34,19 +34,6 @@ class RgbSdkFlutterPlugin :
         )
     }
 
-    private fun unsupported(operation: String): Nothing {
-        throw FlutterError(
-            code = "unsupported",
-            message = "$operation is not implemented yet.",
-            details = bridgeErrorDetails(
-                operation = operation,
-                category = "unsupported",
-                retryable = false,
-                extra = mapOf("phase" to "rln-parity", "feature" to operation)
-            )
-        )
-    }
-
     private fun <T> runRln(operation: String, block: () -> T): T {
         try {
             @Suppress("UNCHECKED_CAST")

doc/API_COMPATIBILITY_AND_DIVERGENCE.md

@@ -31,6 +31,7 @@ ship.
 | `createBackup` / `rlnBackup` | Native artifact owner plus Flutter maintainer | `API-019`, `G-11` | Keep native-blocked and fail before claiming recovery support. | `test/utexo_wallet_test.dart::keeps local backup explicitly native-blocked`; Android/iOS native backup-blocked bridge cases. | Pinned native RLN exposes a working backup/recovery implementation and cross-platform funded recovery tests pass. |
 | `sendRgb(skipSync: true)` | Flutter maintainer | `API-006` | Fail fast instead of accepting and silently discarding the value. | `test/rln_client_contract_test.dart::sendRgb rejects skipSync true before native call`; Android/iOS native skip-sync rejection cases. | Pinned native RLN exposes a real skip-sync request field and RN/core define semantics. |
 | `gossipRgsServerUrl` unlock field | Flutter maintainer | `API-030` | Reject non-empty values because native signer unlock currently ignores the field. | `test/utexo_wallet_test.dart::rejects no-op gossip RGS unlock configuration`. | Pinned native RLN signer unlock consumes the field end to end. |
+| Fractional native fee rates | Flutter maintainer | `MODEL-014` | Require integer-equivalent sats/vbyte and reject fractional values before native execution. RN currently defaults some calls to `1.5`, then truncates through the UInt64 bridge; Flutter does not reproduce that data-loss bug. | Dart wallet validation plus mirrored Android/iOS bridge numeric vectors. | Native/core adopt an exact fractional fee-rate representation end to end. |
 | High-level CFA/UDA issuance | Flutter maintainer | `API-017` | Expose only through low-level RN-parity `RlnClient`/`RLNBinding`, not the stable wallet facade. | Wallet matrix excludes `issueAssetCfa`/`issueAssetUda`; low-level matrix keeps the RN methods. | RN adds wallet-level CFA/UDA methods or product approves a Flutter-only extension library. |
 | Standalone account-key Schnorr signing default | Flutter maintainer plus release security owner | `SEC-007` | Fail closed by default and require `SchnorrSigningMode.experimentalDart` for the pure-Dart signer, even though RN's top-level core `signMessage` is callable by default. Wallet/node-key signing remains native RLN-backed and RN-aligned. | `test/crypto_bip340_vectors_test.dart::standalone Schnorr signing fails closed without explicit opt in`; `test/utexo_wallet_test.dart::signs and verifies RN-core compatible Schnorr messages`; `tool/validate_codebase_hardening.dart`. | Replace the pure-Dart implementation with a vetted/native signing primitive or complete a formal crypto review proving production suitability, then update public docs and parity tests before changing the default. |
 | Durable credential storage | Consuming app owner plus Flutter maintainer | `SEC-009` | App-owned storage boundary; SDK owns only in-memory minimization and diagnostics. | `doc/INTEGRATION_SECURITY_AND_RELEASE.md`; release package validation requires `SECURITY.md`. | SDK product scope expands to include a native secure-storage subsystem. |
@@ -48,7 +49,7 @@ carrier. Raw RN/native parity symbols must live behind
 | --- | --- | --- | --- |
 | Stable facade | App-facing APIs intended to survive release. | `RgbSdkFlutter`, `UtexoWallet`, signer config, domain wallet DTOs. | Breaking changes require a tracker row, migration note, API snapshot update, and semver plan. |
 | Advanced parity | RN/native-shaped APIs for parity testing, diagnostics, migration tooling, and explicit escape hatches. | `RlnClient`, `RLNBinding`, `RLNManager`, `IRLN*`, raw `Rln*` models, native bridge mapper. | Can change when RN/native changes, but changes must cite the RN baseline and update parity tests. |
-| Compatibility shim | Legacy or transitional exports kept to avoid abrupt local breakage. | Old aliases, core-shaped helpers, raw status helpers. | Must be deprecated or quarantined before production release. |
+| Compatibility shim | A narrowly documented RN spelling kept outside the stable root. | Advanced `decodeRGBInvoice`. | Must remain advanced-only and is removable when migration consumers no longer need it. |
 | Unsupported/native-blocked | Public names that exist only to fail honestly. | `createBackup` while native backup is blocked. | Must fail before native side effects and must be documented as not release-ready. |
 | Internal | Implementation details. | Native stores, bridge error mapper internals, LSP implementation helpers. | Must not be exported from the stable facade once `CODE-001` is closed. |
 
@@ -93,6 +94,9 @@ semantics and the adaptation is tested.
 | On-chain receive/send requests | Core uses domain request/response models; RN often passes object literals. | Flutter uses typed request classes. | Typed request classes are allowed if units, optionality, defaults, and native field names are documented. | `MODEL-016`, `API-014`, and `test/utexo_wallet_test.dart::documents and preserves timestamp and amount units at model boundaries`. |
 | Raw request DTOs | RN/native bridge sends loose JS objects and maps. | Low-level `RlnClient` still exposes raw maps through `rgb_sdk_flutter_advanced.dart`. | Raw map APIs stay advanced-only; stable facade must return domain models. | `CODE-001`, `CODE-005`, and API snapshot gate. |
 | Wallet facade return shapes | RN/native names may surface bridge DTOs. | Canonical `UtexoWallet` methods return stable domain DTOs; native `Rln*` models are reachable through explicit `Raw` methods. | Flutter app code should not consume bridge wire shapes by default. Raw access remains available for parity debugging and advanced native integration. | `API-007`, `API-010`, `test/utexo_wallet_test.dart::maps Bitcoin list methods to domain DTOs and raw escape hatches`, `test/utexo_wallet_test.dart::maps Lightning, peer, and channel methods to stable DTOs`. |
+| Lightning payment and status DTOs | Core beta.7 defines `LightningPayment`, `LightningSendRequest`, `ListLightningPaymentsResponse`, `SendPaymentResult`, and canonical string statuses. | Flutter exposes the same domain fields with Dart nullability, immutable list wrappers, and `Rln*StatusValue` string aliases. | Stable methods normalize statuses to PascalCase, preserve optional list status/consignment fields, derive `inbound`, and fail closed when required native payment identifiers are absent. Raw bridge responses remain advanced-only. | `API-037`, `CODE-017`, wallet malformed-success and Lightning mapping tests, and the complete wallet return-shape parity gate. |
+| Wallet facade input shapes | RN uses request objects for many operations and hides low-level sync/filter controls from canonical reads. | Dart uses typed request DTOs or named parameters with the same units, optionality, defaults, and domain names. | Stable methods do not expose raw bridge-only controls or duplicate sats/msats aliases. Advanced `Raw` methods retain native controls. Channel inputs use core names, and `RgbInvoiceRequest.witness` preserves RN on-chain receive behavior. | `API-038`, stable-wallet API snapshot, high-risk input-contract parity checks, wallet tests, and integration smokes. |
+| VSS fence recovery lifecycle | RN documents `vssClearFence` for a locked node before unlock. | Flutter requires `init()` and deliberately does not require `unlock()`. | This is the same lifecycle point expressed through Flutter's explicit state machine. Calling before init or after disposal fails with the SDK taxonomy. | `LIFE-016`, `test/utexo_wallet_test.dart::clears a stale VSS fence after init and before unlock`. |
 
 ## Deprecation and Breaking-Change Plan
 

doc/PUBLIC_API_REFERENCE.md

@@ -10,17 +10,51 @@ The release verdict remains controlled by
 | Tier | Symbols | Contract |
 | --- | --- | --- |
 | Stable wallet facade | `package:rgb_sdk_flutter/rgb_sdk_flutter.dart`: `RgbSdkFlutter`, `UtexoWallet`, wallet config/request/response types, signer strategies, domain DTOs, public wallet errors | Intended for app code, subject to documented breaking-change policy. |
-| Advanced/native bridge | `package:rgb_sdk_flutter/rgb_sdk_flutter_advanced.dart`: `RlnClient`, `RLNBinding`, `RLNManager`, `IRLN*`, raw `Rln*` native models, native bridge error mapper, logger, and RN compatibility extensions | Available for RN/native parity, diagnostics, migration tools, and explicit escape hatches; shape follows the pinned RN/native baseline. |
+| Advanced/native bridge | `package:rgb_sdk_flutter/rgb_sdk_flutter_advanced.dart`: `RlnClient`, `RLNBinding`, `RLNManager`, `IRLN*`, raw `Rln*` native models, `createAdvancedUtexoWallet`, native bridge error mapper, logger, and RN/raw compatibility extensions | Available for RN/native parity, diagnostics, migration tools, and explicit escape hatches; shape follows the pinned RN/native baseline. |
 | Core/domain adapters | Stable domain `Core*`/`Lightning*` DTOs are root-exported; raw mapper extensions remain advanced-only | Flutter domain adaptation of current RN/core concepts. |
-| Compatibility stubs | PSBT and backup/recovery-related symbols | Present for compatibility only when the tracker marks the feature unsupported or native-blocked. |
+| Capability and blocked boundaries | Absent PSBT/begin-end carriers and native-blocked backup/recovery | Optional carriers are `null`; backup fails explicitly while the tracker marks it native-blocked. |
 
 Canonical `UtexoWallet` methods return stable wallet/domain DTOs, not raw
 native wire DTOs. Advanced callers that need the pinned native shape for parity
 debugging must use the matching explicit `Raw` method, for example
 `listChannelsRaw()`, `getBtcBalanceRaw()`, `decodeLnInvoiceRaw()`, or
-`listTransfersRaw()`. Import `rgb_sdk_flutter_advanced.dart` for raw bridge
-classes, RN-uppercase compatibility spellings such as `decodeRGBInvoice`, or
-RN-style managers. The root import intentionally does not export those names.
+`listTransfersRaw()`. Those methods are members of the advanced-only
+`UtexoWalletRawApi` extension; importing the stable root alone cannot resolve
+them. Import `rgb_sdk_flutter_advanced.dart` for raw bridge classes,
+dependency-injected test wallets, RN-uppercase compatibility spellings such as
+`decodeRGBInvoice`, or RN-style managers. The root import intentionally does
+not export those names or expose `RlnClient`/`RLNBinding` in the stable wallet
+constructor.
+
+Custom signer strategies implement `RlnSigner` against the stable
+`RlnSignerHost` protocol. The wallet supplies that host and retains native
+client ownership; signer implementations must not retain it after an
+operation. `IUtexoLspClient` is likewise a stable transport protocol because
+RN exports that contract and `UtexoLsp` accepts injected implementations. The
+concrete HTTP client and raw native client remain advanced-only.
+
+Asset issuance returns `CoreAssetNia`/`CoreAssetIfa`, `inflate()` returns
+`InflateAssetIfaResponse`, `estimateFeeRate()` returns
+`FeeEstimationResponse`, and `checkIndexerUrl()` returns
+`IndexerCheckResponse`. Their native `Rln*` equivalents are available only
+through the advanced raw extension.
+
+Canonical wallet inputs follow RN/core semantics with Dart named parameters or
+typed requests. Read/list/refresh methods do not expose raw bridge sync/filter
+knobs. Lightning invoice creation accepts sats plus an optional
+`LightningAsset`; payment accepts required `lnInvoice` plus optional sats and
+asset fields. Channel opening uses `peerPubkey`, `isPublic`, and
+`assetLocalAmount`. `RgbInvoiceRequest.witness` selects the `onchainReceive`
+mode; the dedicated blind/witness methods enforce their named mode.
+
+Lightning methods use the core beta.7 domain shapes. `listPayments()` returns
+`LightningPayment` records with a required canonical PascalCase status and
+optional Unix-second timestamps. `listLightningPayments()` wraps
+`LightningSendRequest` records, whose status and RGB consignment endpoint are
+optional. `keysend()` returns `SendPaymentResult`. Missing required native
+identifiers and malformed boolean/string success fields throw
+`NativeProtocolException`; the facade never substitutes an empty identifier or
+silently treats malformed data as `false`.
 
 ## Lifecycle Prerequisites
 
@@ -30,6 +64,11 @@ need a running native node. After `shutdown()`, regular operations fail until
 `reinit()` succeeds. After `destroy()`, the wallet is disposed and cannot be
 reused.
 
+`vssClearFence(password)` is the deliberate exception to the general unlock
+rule: call it after `init()` but before `unlock()` when recovering a stale VSS
+single-writer fence. It fails before initialization and does not require an
+unlocked node. `backupNow()` still requires an unlocked node.
+
 Internally, the wallet facade routes native node operations through its binding
 owner so app-facing calls share one serialized lifecycle/operation queue. Signer
 strategies may still use the same underlying native client for their private
@@ -74,8 +113,8 @@ example `RlnNodeInfo.channelAssetMaxAmount` is `BigInt?`.
 
 `NetworkEndpoints` and `getNetworkDefaults()` are stable root helpers for
 app-facing network defaults. They expose the selected indexer URL and RGB proxy
-endpoint after SDK network normalization; lower-level UTEXO preset maps remain
-advanced/internal compatibility surface.
+endpoint after SDK network normalization. Removed UTEXO bridge/network preset
+maps are not retained as dead compatibility code.
 
 `UtexoWallet.listTransfers()` calls the native unfiltered listing path. If the
 pinned native artifact rejects that call, the SDK throws
@@ -161,15 +200,18 @@ root checklist and are snapshotted by `tool/api_snapshot.json`.
 - `ApayNewResponse`, `Assignment`, `BadRequestError`, `BeginEndWalletCarrier`
 - `ChannelReadyInfo`, `ClaimResult`, `ConfigurationError`, `ConflictError`
 - `CoreAsset`, `CoreAssetBalance`, `CoreAssetCfa`, `CoreAssetIfa`
-- `CoreAssetNia`, `CoreAssetUda`, `CoreBalance`, `CoreBtcBalance`
-- `CoreInvoiceData`, `CoreInvoiceReceiveData`, `CoreListAssets`, `CoreRgbAllocation`
-- `CoreTransaction`, `CoreTransfer`, `CoreTransferStatus`, `CoreTransferStatuses`
+- `CoreAssetNia`, `CoreAssetToken`, `CoreAssetUda`, `CoreBalance`, `CoreBlockTime`
+- `CoreBtcBalance`, `CoreInvoiceData`, `CoreInvoiceReceiveData`, `CoreListAssets`, `CoreMedia`
+- `CoreRgbAllocation`, `CoreTokenAttachment`, `CoreTransaction`, `CoreTransfer`
+- `CoreTransferStatus`, `CoreTransferStatuses`, `CoreTransferTransportEndpoint`
 - `CoreUnspent`, `CoreUtxo`, `CreateHodlInvoiceParams`, `CryptoError`
 - `DecodedLightningInvoice`, `GeneratedKeys`, `HodlInvoice`, `HodlInvoiceResult`
 - `ExperimentalCryptoException`
-- `InflateAssetIfaRequest`, `LightningAddressInfo`, `LightningAsset`, `LightningChannel`
-- `LightningChannelOpenResult`, `LightningInvoiceStatus`, `LightningPayment`, `LightningPaymentResult`
-- `LightningPaymentSummary`, `LightningPeer`, `LightningReceiveRequest`, `LightningSendRequest`
+- `FeeEstimationResponse`, `IndexerCheckResponse`, `InflateAssetIfaRequest`, `InflateAssetIfaResponse`
+- `IUtexoLspClient`
+- `LightningAddressInfo`, `LightningAsset`, `LightningChannel`
+- `LightningChannelOpenResult`, `LightningPayment`, `LightningPeer`
+- `LightningReceiveRequest`, `LightningSendRequest`, `SendPaymentResult`
 - `ListLightningPaymentsResponse`, `LspAmountOutOfRangeException`, `LspApayInvoiceProofWire`, `LspChannelTimeoutException`
 - `LspClientConfig`, `LspError`, `LspGetInfoResponse`, `LspLightningAddressByPubkeyResponse`
 - `LspLightningReceiveRequest`, `LspLightningReceiveResponse`, `LspLiquidityTimeoutException`, `LspLnParams`
@@ -184,7 +226,7 @@ root checklist and are snapshotted by `tool/api_snapshot.json`.
 - `RgbNodeError`, `RgbSdkException`, `RgbSdkFlutter`, `RgbSendRequest`
 - `RlnInvoiceStatusValue`, `RlnInvoiceStatuses`, `RlnKeyMaterial`, `RlnMnemonicKeyMaterial`
 - `RlnOperationTimeoutException`, `RlnOperationTimeoutPolicy`, `RlnPaymentStatusValue`, `RlnPaymentStatuses`
-- `RlnSeedBytesKeyMaterial`, `RlnSeedHexKeyMaterial`, `RlnSigner`, `SDKError`
+- `RlnSeedBytesKeyMaterial`, `RlnSeedHexKeyMaterial`, `RlnSigner`, `RlnSignerHost`, `SDKError`
 - `SchnorrSigningMode`, `SendAssetOptions`, `SendAssetResult`, `SignMessageParams`
 - `UnsupportedWalletFeatureException`
 - `UtexoLsp`, `UtexoLspConfig`, `UtexoUnlockConfig`, `UtexoWallet`
@@ -198,7 +240,7 @@ root checklist and are snapshotted by `tool/api_snapshot.json`.
 - `isSameLspHost`, `isTerminalPaymentStatus`, `isUmaAddress`, `lnurlDiscoveryUri`
 - `normalizeInvoiceStatus`, `normalizeLightningAddress`, `normalizeNetwork`, `normalizePaymentStatus`
 - `normalizeReceiveStatus`, `normalizeSeedInput`, `parseCoreAssignment`, `parseCoreOutpoint`
-- `parseLightningAddress`, `peerUri`, `redactSupportText`, `resolveUnlockConfig`
+- `parseLightningAddress`, `peerUri`, `redactSupportText`
 - `resolveUnlockParams`, `restoreKeys`, `seedFromMnemonic`, `signMessage`
 - `signSchnorr`, `toUnitsNumber`, `tryNormalizeInvoiceStatus`, `tryNormalizePaymentStatus`
 - `validateBase64`, `validateBip39Mnemonic`, `validateHex`, `validateMnemonic`