Wasm followup (#82)

* Wasm followup cleanup

* Add tools in docker

Author: rmn-boiko

.dockerignore

@@ -12,8 +12,10 @@
 !src/
 !migration/
 !build.rs
+!tools/
 
 # but still ignore these
 rust-lightning/.git
 rust-lightning/.github
 rust-lightning/.gitignore
+tools/wasm-proxy-gateway/target

bindings/wasm-sdk/ARCHITECTURE.md

@@ -5,7 +5,7 @@ This document is the **canonical architecture reference** for the WASM-related s
 - **WASM SDK crate**: `bindings/wasm-sdk` (browser-facing `wasm-bindgen` SDK)
 - **WS↔TCP gateway + dev helpers**: `tools/wasm-proxy-gateway`
 - **Browser E2E**: `e2e-specs` + `scripts/ci/wasm_regular_rln_e2e.sh`
-- **Shared contracts**: `src/sdk/contracts` (types + stable error strings + drift fixtures)
+- **Shared contracts**: the `sdk-contracts` crate (git dependency; types + stable error strings)
 
 ## Components
 
@@ -66,10 +66,10 @@ flowchart LR
   BrowserDemo -->|submitFundingTransaction*| BrowserWasm["Browser WASM (LDK)"]
 ```
 
-## Contracts and drift prevention
+## Contracts
 
-- **Shared contract types + stable error strings** live in `src/sdk/contracts`.
-- **Golden JSON fixtures** are enforced by `cargo test -p sdk-contracts`.
+- **Shared contract types + stable error strings** live in the `sdk-contracts` crate,
+  consumed as a git dependency (see `bindings/wasm-sdk/Cargo.toml`).
 
 ## How to run
 

bindings/wasm-sdk/LN_WASM_NATIVE_PARITY_SPEC.md

@@ -1,83 +1,72 @@
-# LN WASM Native Parity Spec
+# LN WASM Native Parity
 
 ## Purpose
 
-This document freezes the implementation scope and acceptance criteria for
-fully native LN behavior in browser WASM (Mutiny-style runtime model), while
-keeping existing RLN SDK API contracts stable.
-
-This is the source of truth for:
-
-- what "fully ported LN behavior" means,
-- which infra is still external,
-- and what tests must pass before declaring parity complete.
+This document describes how LN behavior runs natively in browser WASM
+(Mutiny-style runtime model) while keeping the existing RLN SDK API contracts
+stable. It covers what "native LN behavior" means here, which infra stays
+external, and which behaviors the test suite exercises.
 
 ## Scope Boundary
 
-### In scope (must be native in WASM)
+### Native in WASM
 
-1. LN runtime state machine authority is local in WASM (no RLN runtime bridge
-   service as LN decision-maker).
+1. The LN runtime state-machine authority is local in WASM (no RLN runtime
+   bridge service acts as the LN decision-maker).
 2. Peer/session/channel/payment state transitions are event-driven from local
    LDK runtime components.
 3. Runtime persistence/recovery works across page reload and browser restart.
-4. Public wasm node/sdk APIs return deterministic contracts equivalent to
+4. Public wasm node/sdk APIs return deterministic contracts equivalent to the
    existing SDK semantics.
 
-### Out of scope (external infra remains required)
+### External infra required
 
 1. Relay/proxy service for browser websocket transport bridging.
 2. Bitcoin chain source/indexer (Esplora).
 3. RGB transport endpoint.
 4. Funding/signing providers (wallet signer integration for on-chain tx flows).
 
-## Definition of Done (Parity)
-
-Parity is complete only when all are true:
+## Parity Properties
 
 1. LN payment and channel lifecycle transitions are driven by local runtime
    events, not manual status APIs.
-2. Runtime can recover channel/payment state after reload without corruption.
+2. The runtime recovers channel/payment state after reload without corruption.
 3. `open_channel`, `close_channel`, `create_ln_invoice`, `send_payment`,
-   `keysend`, `invoice_status`, `list_payments`, `get_payment` match frozen
-   contracts for:
-   - input validation (IV),
-   - state transitions (ST),
-   - output shape (OS),
-   - error contracts (EC).
+   `keysend`, `invoice_status`, `list_payments`, and `get_payment` honor stable
+   contracts for input validation (IV), state transitions (ST), output shape
+   (OS), and error contracts (EC).
 4. Virtual channel logic is bound to real runtime state and safety checks.
-5. Browser integration tests (not only compile checks) are green in CI.
 
-## Behavioral Contract Freeze
+## Behavioral Contracts
 
 ### Runtime authority
 
-1. Local runtime owns truth for peers/channels/payments.
+1. The local runtime owns truth for peers/channels/payments.
 2. API read methods (`node_info`, `network_info`, list/get APIs) read from
-   runtime state, not from local ad-hoc shadow state.
+   runtime state, not from ad-hoc shadow state.
 
 ### Payments
 
-1. `pending -> claimable/claiming/succeeded/failed/expired/cancelled` transitions
-   must obey strict transition rules.
+1. `pending -> claimable/claiming/succeeded/failed/expired/cancelled`
+   transitions obey strict transition rules.
 2. Terminal state regressions are rejected with deterministic errors.
 3. Swap/runtime observers and RGB-LN transfer observers receive the same final
    status.
 
 ### Channels
 
-1. `open -> usable -> closing/closed` semantics remain deterministic.
-2. Reconnect must not duplicate live channels or peers.
-3. Channel close safety checks must be consistent across restart/recovery.
+1. `open -> usable -> closing/closed` semantics are deterministic.
+2. Reconnect does not duplicate live channels or peers.
+3. Channel close safety checks are consistent across restart/recovery.
 
 ### Recovery
 
-1. Snapshot schema is versioned.
-2. Checkpoint protocol is crash-safe (pending+committed recovery semantics).
-3. Recreated node handle for same runtime key restores state without manual
-   repair.
+1. The snapshot schema is versioned.
+2. The checkpoint protocol is crash-safe (pending+committed recovery semantics).
+3. A recreated node handle for the same runtime key restores state without
+   manual repair.
 
-## Acceptance Test Matrix (Must be Green)
+## Test Coverage
 
 ### A. Runtime lifecycle and recovery
 
@@ -122,23 +111,12 @@ Parity is complete only when all are true:
 2. SDK facade forwarding parity.
 3. SDK node-handle forwarding parity.
 
-## CI Gate Requirements
-
-1. `cargo check --target wasm32-unknown-unknown` (wasm-sdk crate).
-2. `cargo test --target wasm32-unknown-unknown --no-run` (wasm-sdk crate).
-3. Browser wasm test execution job (wasm-bindgen test path) for contract tests.
-
-The crate targets `wasm32` only (the `real-wasm-rgb` backend feature is on by default), so all
-compile checks use the wasm32 target.
-
-Parity cannot be declared complete until all three gate groups are green on CI.
-
-## Tracking Convention
+## Build and test commands
 
-For every parity work item, include:
-
-1. module/file ownership,
-2. contract impact (IV/ST/OS/EC),
-3. test id(s) added/updated,
-4. CI gate affected.
+The crate targets `wasm32` only (the `real-wasm-rgb` backend feature is on by
+default), so all compile checks use the wasm32 target:
 
+1. `cargo check --target wasm32-unknown-unknown` (wasm-sdk crate) — run in CI.
+2. `cargo test --target wasm32-unknown-unknown --no-run` (wasm-sdk crate).
+3. Browser wasm test execution (`scripts/run-browser-tests.sh`, wasm-bindgen
+   test path) for the contract tests — run locally.

bindings/wasm-sdk/README.md

@@ -11,8 +11,8 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for the consolidated WASM stack overview
 ## Scope
 
 - Target: browser and Node.js consumers via `wasm-bindgen` output.
-- Focus: SDK parity where feasible in WASM.
-- Current intentional gap: `issue_asset_uda` remains unsupported for now.
+- Focus: SDK parity in WASM.
+- `issue_asset_uda` is unsupported (no UDA primitive in `rgb-lib-wasm`).
 
 For endpoint-level status, see [SDK_WASM_ENDPOINT_MATRIX.md](SDK_WASM_ENDPOINT_MATRIX.md).
 
@@ -62,11 +62,11 @@ docker compose -f compose.wasm.yaml up -d
 
 This brings up:
 
-- RGB proxy: `127.0.0.1:3005` (host port mapped from compose `proxy`)
+- RGB proxy: `127.0.0.1:3000` (host port mapped from compose `proxy`)
 - WASM proxy gateway: `127.0.0.1:3001`
 - Esplora HTTP: `127.0.0.1:3002`
-- Electrum: `127.0.0.1:50011` (host port mapped from compose `electrs`)
-- Bitcoind RPC: `127.0.0.1:19443` (host port for `compose.wasm-infra.yaml` / `compose.wasm.yaml` bitcoind)
+- Electrum: `127.0.0.1:50001` (host port mapped from compose `electrs`)
+- Bitcoind RPC: `127.0.0.1:18443` (host port mapped from compose `bitcoind`)
 
 Build WASM package for browser examples:
 
@@ -111,18 +111,12 @@ model) and avoids REST coupling.
 
 ## CI
 
-WASM checks are wired into CI in `.github/workflows/test.yaml`:
+WASM checks run in `.github/workflows/test.yaml`: the `feature-matrix` job's
+`wasm-without-vls` mode runs `cargo check --target wasm32-unknown-unknown` against
+`bindings/wasm-sdk/Cargo.toml`. The package `pkg/` artifact is built separately by
+`.github/workflows/wasm-artifacts.yaml` via `wasm-pack build`.
 
-- `wasm-sdk` (wasm32 crate check + test-binary compile)
-- `wasm-sdk-wasm32` (target compatibility check)
-- `wasm-sdk-browser` (blocking headless browser run in Chrome)
-- `wasm-sdk-browser-diagnostic-firefox` (non-blocking diagnostic run in Firefox)
-
-Both browser jobs pin:
-- `wasm-pack` to `0.13.1`
-- `wasm-bindgen-test-runner` to `0.2.117` (verified in CI after test bootstrap)
-
-Local browser test command (same wrapper used by CI):
+Run the browser unit tests locally (not run in CI):
 
 ```sh
 WASM_BINDGEN_TEST_TIMEOUT=300 WASM_TEST_BROWSER=chrome ./bindings/wasm-sdk/scripts/run-browser-tests.sh

bindings/wasm-sdk/RGB_WASM_PROXY_TRANSPORT_SPEC.md

@@ -1,29 +1,27 @@
-# RGB WASM Proxy Transport Spec
+# RGB WASM Proxy Transport
 
 ## Purpose
 
-This document freezes the architecture boundary for porting RGB business logic
-to native wasm runtime while routing RGB network transport through a proxy
+This document describes the architecture boundary: RGB business logic runs in
+the native wasm runtime, while RGB network transport is routed through a proxy
 service colocated with LN websocket proxying.
 
-This is the scope/contract baseline for the RGB-native migration track.
-
 ## Scope Boundary
 
-### In scope (must become wasm-native)
+### Native in the wasm runtime
 
-1. RGB transfer orchestration and lifecycle state transitions in wasm runtime.
+1. RGB transfer orchestration and lifecycle state transitions.
 2. RGB runtime persistence and recovery in browser storage.
 3. Deterministic wasm API contracts for RGB operations and status surfaces.
 4. LN<->RGB status synchronization in wasm runtime observers.
 
-### Out of scope (external infra still required)
+### External infra required
 
 1. RGB network transport service itself (provided by proxy upstream).
 2. Bitcoin chain source/indexer (Esplora).
 3. Funding/signing provider integration for on-chain tx flows.
 
-## Proxy Contract (Frozen)
+## Proxy Contract
 
 Browser-facing routes (example):
 
@@ -38,26 +36,20 @@ Transport contract requirements:
 4. Tenant isolation: requests for one session/node cannot access another session.
 5. Request size/time limits and rate limiting are enforced.
 
-## Wasm Runtime Contract (Frozen)
+## Wasm Runtime Contract
 
-1. Wasm runtime is authoritative for RGB transfer state machine.
-2. Proxy is transport-only; business decisions are not delegated to proxy.
+1. The wasm runtime is authoritative for the RGB transfer state machine.
+2. The proxy is transport-only; business decisions are not delegated to it.
 3. Runtime state persistence uses browser-backed storage with deterministic
    recovery semantics.
-4. Error contracts returned by wasm APIs remain deterministic and documented in
+4. Error contracts returned by wasm APIs are deterministic and documented in
    `ERROR_CONTRACT.md`.
 
-## Deliverables
-
-1. This boundary/spec document.
-2. README reference to this document.
-3. No behavior changes are required by this document.
-
-## Exit Criteria
+## Responsibility split
 
-1. Team agrees on responsibility split (wasm runtime vs proxy).
-2. No ambiguous ownership for transport, state, or auth/session logic.
-3. Follow-up implementation steps can proceed without redefining boundaries.
+The wasm runtime owns RGB transfer state, persistence, and auth/session logic;
+the proxy owns only transport. There is no shared ownership of transport, state,
+or auth/session logic across the boundary.
 
 ## RGB on the LN peer link (not the HTTP proxy)