local-dev/dapp-builder: lessons learned from freenet-email v0.1.x publish + debug

[iduartgomez]

Captured during freenet-email v0.1.0/v0.1.1 production publish and identity-creation debugging (April 2026). Filing so local-dev and dapp-builder skills absorb the gotchas before the next dApp hits them.

1. Gateway iframe shell + same-origin WebSocket check

The gateway wraps every webapp in a sandboxed iframe at ?__sandbox=1. The parent shell (freenetBridge) intercepts window.WebSocket from inside the iframe and proxies to the real node WS via postMessage.

The bridge enforces strict origin equality:

const LOCAL_API_ORIGIN = location.origin;  // e.g. "http://127.0.0.1:7509"
if (httpProto + '//' + u.host !== LOCAL_API_ORIGIN) reject;

host includes hostname, so localhost ≠ 127.0.0.1. Hardcoding ws://localhost:7509/... in the dApp breaks the moment the page is opened by IP (or vice versa).

Fix pattern — derive WS URL from window.location at runtime:

let host = window().location().host()?;  // "127.0.0.1:7509"
let scheme = if location.protocol()? == "https:" { "wss" } else { "ws" };
let url = format!(\"{scheme}://{host}/v1/contract/command?encodingProtocol=native\");

Skill should warn against hardcoded WS URLs and document the bridge's origin check.

2. wasm-bindgen onerror shim crash

Bridge proxy fires new Event('error') (no filename/message). wasm-bindgen's onerror handler calls event.filename → undefined → wbg crash:

wasm-bindgen: imported JS function that was not marked as 'catch' threw an error: expected a string argument, found undefined

Surfaces as a console error during normal operation. Smoke tests asserting consoleErrors === [] will fail. Allowlist the message until wbg upstream fixes, or use --catch on the import.

3. fdev port targeting

fdev defaults to port 7509. Targeting an isolated test node needs:

fdev --port 7510 execute put ...           # CLI flag
WS_API_PORT=7510 cargo make publish-...    # env override for cargo-make

Argument order matters: --port before execute, --code/--parameters before the contract subcommand. Skill already says this — worth a more prominent callout because the failure mode is put failed after 4 attempts which gives no hint about port.

4. Monotonic version requirement for web-container updates

On-chain web-container update check is strictly monotonic. Common broken schemes:

• commit-hash hex truncated to u32 — not monotonic, newer commit can hash lower
• commit count (git rev-list --count HEAD) — monotonic per branch but starts at ~22, far below versions already accepted under broken schemes

Working scheme: date -u +%s (unix timestamp at sign time). Tradeoff: contract IDs no longer reproducible from source — the committed snapshot becomes the authoritative ID.

5. Persistent vs ephemeral test nodes

--id creates ephemeral temp directories wiped on restart, destroying delegate secrets (signing keys, app data). Use --data-dir for persistent isolation. Skill already covers — keep.

6. Mobile browser WASM cache

Firefox mobile especially aggressive. After republish, clear cache or use ?_v={timestamp} cache-buster. Skill covers — keep.

7. Delegate-not-found loop (open question)

Observed during identity-management delegate calls on a fresh local node:

Delegate not found in store (expected for migration probes) delegate_key=Cu...
Module cache miss — compiling

Loops indefinitely on each call. Suggests delegate registration not persisting between calls, or migration probe path is hot. Worth investigating + documenting in skill if it's a known pattern.

8. GNU tar requirement

compress-webapp needs --sort=name --mtime=… --owner=0 --group=0 flags only GNU tar supports. macOS BSD tar silently produces non-reproducible archives. Install gnu-tar brew and detect gtar. Worth mentioning in dapp-builder when scaffolding signed-webapp pipelines.

9. Browser MCP for dApp debugging

chrome-devtools MCP + Playwright MCP both work for diagnosing UI ↔ node interaction. Particularly useful for:

• reading actual gateway shell HTML (to find bridge origin checks)
• capturing console errors invisible on mobile
• watching network requests against the node WS

Could be a local-dev subsection: "Debugging dApps via browser MCP".

Suggested skill changes

• local-dev: add "Gateway iframe + WS origin check" section with the window.location derivation pattern
• local-dev: expand fdev port section with the WS_API_PORT env var
• dapp-builder: add "Reproducible signed webapps" section covering monotonic version, GNU tar, committed-snapshot vs reproducible-from-source tradeoff
• dapp-builder: add "WebSocket URL derivation" as a required pattern when the dApp loads inside the gateway iframe
• Either: capture the wbg onerror crash as a known noise pattern + smoke-test allowlist guidance

[iduartgomez]

Update — debug patterns from cross-node QA (May 2026)

Pulling out reusable patterns rather than the specific bug list. Specific issues are filed in their own repos. These are skill-level guidance.

Pattern: when contract logging doesn't appear, suspect the runtime

If you've added freenet_stdlib::log::info(...) at the very first line of update_state and that log line never appears for a transaction that should have hit it, the runtime is panicking before the WASM was even invoked. Don't keep instrumenting the contract — start reading freenet-core source for the variant or code path that's blowing up.

We chased this exact failure mode for several iterations: patched the contract three times, the UI twice, all on the assumption the WASM was being entered. The contract's first log line was the canary that proved otherwise.

Skill action: local-dev "debugging contracts" — the moment your contract's entry-line log doesn't appear, assume runtime crash and pivot.

Pattern: deterministic-build dev-loop trap

fdev build produces byte-deterministic WASM. Code-hash output is identical across edits unless cargo clean ran. Touching lib.rs doesn't rebuild a WASM with new content because the existing WASM hashes the same — the rust toolchain's incremental compile sees the source as semantically unchanged from the previously-compiled artifact's perspective.

During development, after editing the contract source:

cargo clean -p <crate> --target wasm32-unknown-unknown
fdev build --features contract

Otherwise debugging in circles is the failure mode. The deterministic build is a feature for releases (committed contract IDs reproduce across machines), but a footgun during dev.

Skill action: local-dev "iterating on a contract" needs this prominently. Verify the code-hash actually changed after each rebuild.

Pattern: subscribe semantics are future-only

ContractRequest::Subscribe registers for future state changes. It does not deliver the current state. If the contract state already changed between when the dApp restored its identities and when its UI subscribed, the UI silently misses the change until the next state change.

Pair every subscribe with a follow-up ContractRequest::Get to catch up:

contract.subscribe(key).await?;
// Catch up on any state change that already landed.
contract.get_state(key).await?;

The Get response surfaces through the same UpdateNotification handler path and populates the local cache.

Skill action: dapp-builder "subscribe + load semantics" section. This is a standard distributed-systems gotcha but it bites every dApp that subscribes on user navigation.

Pattern: fire-and-forget delegate ordering

DelegateRequest::ApplicationMessages calls are not ordered with respect to each other. A dApp that fires Init then CreateIdentity back-to-back can hit the delegate in the wrong order — CreateIdentity racing ahead, finding no seeded secret, erroring silently.

Mitigations (use both):

• Design delegates to be idempotent / lazy-init. Each message handler should treat missing state as "use default" rather than erroring.
• For UI flows that depend on a delegate's state being seeded, await a confirming response from the seed message before issuing dependent messages.

Skill action: dapp-builder delegate section needs an ordering callout.

Pattern: contract delta wire-shape ambiguity

The runtime's BroadcastTo / re-resync path can re-shape a delta payload across hops. A delta a sender encoded as a single-item type may arrive at the receiver wrapped in a whole-record type (or vice versa). If the contract's Delta decode path is rigid (single shape only), the receive side fails with missing field or similar deser error.

Defensive contract pattern:

UpdateData::Delta(d) => match SingleItem::try_from(d.clone()) {
    Ok(item) => state.append(item),
    Err(_) => match WholeRecord::try_from(d) {
        Ok(record) => state.merge(record),
        Err(e) => return Err(ContractError::Deser(format!("{e}"))),
    },
}

Skill action: dapp-builder "delta encoding" section. Don't assume your delta arrives in the shape you sent it.

Pattern: 2-node iso harness for dApp validation

Single-node mocks miss every cross-node propagation, signature-verification, and state-merge issue. dApps that use sibling contracts (e.g. AFT-style spam control where sender + recipient have distinct contracts that reference each other) must be tested against a 2-node harness.

Minimal recipe (scripts/run-isolated-nodes.sh style):

• Two freenet network processes with --skip-load-from-network
• Peer's --gateway 127.0.0.1:31338,<gw_pubkey> pointed at the gateway
• Per-node --data-dir and --log-dir
• Per-node HOME override to defeat global config bleed-through
• Wipe data-dirs between runs to defeat day-1 calendar slot collisions and stale subscriptions

Skill action: local-dev "two-node test setup" should inline a stub harness. Easier than asking dApp authors to write their own.

Pattern: browser MCP for cross-node dApp debugging

When a dApp UI shows the wrong end-state but the contract logs show the right one (or vice versa), the gap is between the runtime and the browser. The diagnostic loop:

1. Run iso 2-node harness
2. Open 2 browser tabs (one per node origin) — different :port gives independent localStorage / WS connections
3. Drive the UI flow via Playwright MCP or chrome-devtools MCP
4. After each click, tail freenet.*.log on both nodes; correlate timestamps with the UI action
5. Browser console errors (browser_console_messages MCP) often show the WS message the UI received but didn't handle — these are often the missing-handler bugs that cause silent misses

Skill action: local-dev should have a "Debugging dApps via browser MCP" subsection. The 2-tab pattern is non-obvious and powerful.

Pattern: when fix doesn't take effect, verify the wire

The chain dApp source → built WASM → on-disk wasm → in-memory module cache → wire payload → received-side decode has many places where an "applied" fix doesn't actually reach the runtime. Diagnostic order:

1. cargo clean + rebuild — does the code-hash change?
2. Check the on-disk WASM matches the built one (shasum -a 256)
3. Check the on-disk WASM has the new strings (strings | grep <new-symbol>)
4. Check the runtime's stored copy matches the on-disk one (it should — but compose paths can leave stale copies)
5. Check the wire payload from request_router logs — does it carry what the dApp sent?
6. Add a log line at the first line of the receiver-side handler. If that line doesn't print, the receiver didn't run.

Skill action: local-dev "fix doesn't seem to apply" section. Each layer can mask the previous.

Suggested skill changes (revised)

• dapp-builder:
  • "Subscribe + load: catch-up Get after every subscribe" — subscribe is future-only
  • "Defensive delta decoding" — try multiple wire shapes, contract Delta paths are fragile across runtime hops
  • "Delegate ordering" — fire-and-forget messages have no order; design idempotent handlers
• local-dev:
  • "Iterating on a contract: cargo clean before each fdev build" — deterministic-build trap
  • "Two-node iso harness" — stub recipe, plus log-tailing pattern
  • "Browser MCP for cross-node debug" — 2-tab pattern + console-error / log-tail correlation
  • "When a fix doesn't seem to apply" — the 6-step verification chain
  • "Contract WASM not entering update_state? It's the runtime, not the contract" — log canary pattern