Syncing daemon release

Syncing to a New wavelength Release

Overview

One pinned daemon revision drives three committed artifacts that must move together: the generated facade types (packages/core/src/generated.ts), the API reference data (apps/docs/src/data/api/wallet.json), and the pin itself (RUNTIME_MANIFEST_VERSION in packages/core/src/version.ts). The wasm runtime asset set is gitignored and staged from the pin, not committed. A sync is complete when the three match the same daemon commit and the verification ladder passes.

All generators read the wavelength checkout at ../wavelength or $WAVELENGTH_DIR. There may be no directory literally named wavelength, so find it by remote (github.com/lightninglabs/wavelength in git remote -v, under any remote name), not by directory name. Do not move the shared checkout to the target commit: it is often behind the remote and may have local edits, so a fast-forward or stash disturbs someone else's working tree. Use a throwaway worktree instead:

cd <daemon checkout> && git fetch <remote> --tags
# <target> is the release tag (v<X.Y.Z>) or, when preparing a sync ahead of
# the tag, the daemon commit SHA. rev-parse on an annotated tag returns the
# tag OBJECT hash, so always dereference with ^{commit}.
git worktree add --detach /tmp/wavelength-<version> '<target>^{commit}'
export WAVELENGTH_DIR=/tmp/wavelength-<version>            # absolute path
# ... run the whole sync ...
cd <daemon checkout> && git worktree remove --force /tmp/wavelength-<version>

What changed upstream -> what to touch here

Upstream change	Regenerate	Hand-update
Facade type fields (sdk/wavewalletdk)	pnpm gen:types	Consumers of renamed fields (git grep <old_field> across packages/, apps/). Every RPC verb is mapped once in packages/core/src/base-client.ts; transports supply only callRaw. requests.ts/results.ts stay hand-authored (see docs/codegen.md)
WalletService RPC added/removed	pnpm gen:api-docs	The RPC checklist below
RPC/field doc comments only	pnpm gen:api-docs	Nothing (pages render from wallet.json)
DaemonService RPCs/messages (waverpc/daemon.proto)	Nothing	wallet.json covers WalletService ONLY, so an empty wallet.json diff after a large daemon.proto change is expected, not a generator failure. It lands as CLI/prose docs work (step 4); wavecli is the DaemonService client, so check cmd_*.go
wavecli flags/commands	Nothing	The command's page in apps/docs/src/content/docs/cli/; a new top-level command also needs a CLI_NAV entry. A change to the GLOBAL flag set, the exit-code table, or the error envelope touches cli.mdx and potentially every command page: grep the whole cli/ directory for the old flag spelling or exit code, not just the changed command's page. A REMOVED one must be deleted in lockstep: its cli/<cmd>.mdx, its CLI_NAV entry, its row in the cli.mdx table, and its slug in apps/docs/tests/cli.spec.ts's hardcoded slug list (git grep -n <cmd> apps/docs finds stragglers)
Daemon operational facts (ports, TLS, build tags, gateway behavior)	Nothing	apps/docs/src/content/docs/api/get-started.mdx and api/rest.mdx; cli.mdx global flags/exit codes
Wasm runtime build	wasm:local (step 5)	Bump the pin first
Runtime asset FILE LIST	Nothing	Three places in lockstep: packages/web/src/runtime-manifest.ts (RUNTIME_ASSET_FILES, and in the same file, generated: RUNTIME_ASSET_DIGESTS), apps/web-wallet-demo/scripts/wasm-local.sh, apps/web-wallet-demo/scripts/fetch-runtime-assets.sh. A fourth lives upstream in wavelength's mobile-bindings.yml: its "Package browser WASM runtime" step lists the files packed into the release archive, so diff that step's list against the three local copies
Gomobile mobile bindings build	bindings:local (step 5)	Bump the pin first. Mirrors the wasm row: build from $WAVELENGTH_DIR, since the pin is often not downloadable yet. bindings:fetch works only once it names a published release
Gomobile facade (sdk/wavewalletdk/mobile)	Nothing	Native SDK docs checkpoint (below)

RPC checklist

Adding or removing a WalletService RPC touches more places than any other change class:

• packages/core: interface in client.ts, types in requests.ts / results.ts, impl in base-client.ts (one place; transports pipe callRaw), the barrel index.ts, and testing/fake-client.ts (it implements WavelengthClient, so a missing method fails typecheck).
• Docs config: API_NAV in apps/docs/src/config/nav.ts (it is there, below the SDK NAV array); API_CLI, API_CLI_INVOCATION, API_SAMPLES in config/api.ts; any new inline reference type in config/api-links.ts (coreSymbols + inlineTypeOwners), or its deep link will not resolve.
• Reference prose: only apps/docs/src/content/docs/reference/wavelength-core.mdx. The web and RN pages re-export core and carry no method list.
• Docs tests hardcoding the method count: apps/docs/tests/nav.spec.ts and api-data.spec.ts assert a literal, as both a numeral and an English word, so grep for both. api-method.spec.ts and agent-artifacts.spec.ts iterate every method, so the new page must build and be reachable.

Ordered procedure

export WAVELENGTH_DIR=/absolute/path/to/wavelength   # a worktree at the
                                                     # release (see Overview)

1. Pin: set RUNTIME_MANIFEST_VERSION in packages/core/src/version.ts to the release tag (v0.1.0), or to the daemon short commit hash when preparing a sync ahead of the tag. Keep the exact single-quoted literal form; scripts/runtime-version.mjs parses the source text. A hash pin is the normal way to get a sync reviewed before the release exists: open the PR on the hash, then flip to the tag before merging. CI's runtime-pin job stays red until the pin names a published release, so expect it red for the whole review, and never merge it red.

2. Types: pnpm gen:types (needs Go + tygo). Review the generated.ts diff, then grep-and-fix hand-authored consumers per the table. Two upstream changes surface as generator problems, both fixed in scripts/gen-types.mts and never by hand-editing generated.ts:

   • A build failure 'any' only refers to a type means the facade added an exported scalar const assigned from another package (e.g. MaxSigningWorkers = waved.MaxSigningWorkers); tygo cannot inline the value and emits export const X = any /* ... */;. gen-types strips such unresolved consts; extend that strip if a new shape slips through.
   • Em-dashes in upstream Go doc comments reach generated.ts verbatim. gen-types sanitizes them to hyphens, so if the em-dash check trips on generated.ts, the sanitizer regressed.

3. API data: pnpm gen:api-docs. Its gates fail loudly by design:

   • Nav drift: update API_NAV (and the curation maps in config/api.ts), then re-run. Never weaken the check.
   • Missing doc comments: fix by adding comments upstream in wallet.proto, never by tolerating empty descriptions.
   • Run it twice; the second run must produce a byte-identical wallet.json.
   • Sample keys in API_SAMPLES must be real request field names (a spec enforces this).

4. CLI/prose docs: author from wavelength source (cmd/wavecli/waveclicommands/cmd_*.go: Flags() registrations with defaults, and which RPC the RunE calls), NEVER from --help output (build tags hide commands, and help text omits exit codes and JSON shapes). Every subcommand gets its own ### section with its own flags table. Verify operational claims against waved/config.go and gateway_server.go.

5. Runtime assets: check the release first (gh release view <pin> --repo lightninglabs/wavelength --json isDraft,assets). If it is published with assets attached, pnpm --filter web-wallet-demo run wasm:fetch and pnpm --filter @lightninglabs/wavelength-react-native run bindings:fetch are both correct and much faster than building, and they exercise the deploy's actual path. Fall back to the :local scripts only for a commit-SHA pin or a draft release.

   pnpm --filter web-wallet-demo run wasm:local builds from $WAVELENGTH_DIR into public/runtime/<version>/ (bump the pin first or it stages under the OLD version). The deploy instead fetches Wavewalletdk.wasm.tar.gz from the release named by the pin. That archive lands on a DRAFT release and draft assets are not publicly downloadable, so a tag-shaped pin that runtime-pin still rejects usually means the release is unpublished, not that the pin is wrong. The RN transport's mobile bindings key off the same pin and need the same treatment: restage them with pnpm --filter @lightninglabs/wavelength-react-native run bindings:local, which builds the .aar and the .xcframework from the same $WAVELENGTH_DIR worktree (pass android or ios to build one platform; Android needs the SDK/NDK and a JDK, iOS needs macOS with Xcode). Both :fetch scripts build a release URL from the pin, so they 404 for a commit-SHA pin (no such release) and for a tag whose release is still a draft (assets not public). Nothing in CI covers the bindings, so a stale staging only shows up on a device build.

   After staging, run pnpm gen:runtime-digests so RUNTIME_ASSET_DIGESTS in packages/web/src/runtime-manifest.ts matches the newly staged set. Digests generated from a wasm:local build against a draft release are provisional: they are only confirmed correct once CI's runtime-pin job passes its digest check against the published release archive.

6. Native SDK docs: run the checkpoint below. It is cheap and usually a no-op, but nothing else in this procedure catches native-page drift.

7. Versions + commits: the packages version in lockstep with the daemon pin; set every packages/*/package.json version to the pinned release (without the v) so the release workflow's tag check passes. Commits use bare area prefixes (core:, web:, docs:, demo:), one logical change each, every commit building on its own.

8. Publish: create a DRAFT GitHub release tagged with the pin (e.g. v0.2.0), targeting main. Draft it as soon as the sync PR is up (drafts create no tag; the tag is minted at publish time from main's tip, so only publish after the merge). Check the pre-release box for any hyphenated version; release.yml refuses to publish a hyphenated tag without it, and the dist-tag follows (stable lands on latest, prerelease on next). Publishing triggers release.yml, which verifies the tag against the package versions and the pin, then publishes all four packages to npm. Nothing publishes until this release is cut. Full procedure and failure modes: RELEASE.md at the repo root.

   Release notes format: an intro line naming the paired wavelength release (linked), then for a prerelease an npm install @lightninglabs/wavelength-web@next snippet. Then the changes since the previous tag, grouped under ## SDK packages, ## Docs site, and ## Demo apps headings (plus ## Maintenance for repo plumbing), one bullet per merged PR in the GitHub auto-notes style: * <concise change> by @<author> in <PR URL>. Source the PR list from the auto-generated notes (gh api releases/generate-notes) so nothing merged since the last tag is missed; a PR whose content spans sections (e.g. a sync PR carrying both the pin and CLI docs) may appear once per section. End with the auto-notes' Full Changelog compare link.

Verification ladder (run in this order)

pnpm build && pnpm typecheck        # build FIRST; typecheck resolves dist/*.d.ts
pnpm test:api-docs                  # extractor unit tests
pnpm --filter @lightninglabs/wavelength-web test
# Docs Playwright: its webServer has reuseExistingServer:true on port 4321, so
# it will silently attach to a stale preview from another worktree/session and
# serve an OLD build (a 404 for a brand-new page is almost always this, not a
# code bug). Pass a free PORT so it builds and serves THIS worktree fresh:
PORT=4399 pnpm --filter @lightninglabs/wavelength-docs test
WAVELENGTH_DIR=... pnpm --filter web-wallet-demo run wasm:local && \
  pnpm --filter web-wallet-demo run build:local && \
  pnpm --filter web-wallet-demo run test   # Playwright smoke test: gold standard
# build:local sets VITE_RUNTIME_INTEGRITY=off; locally built assets from
# wasm:local cannot match the pinned digests that plain `build` enforces.

# No em-dash, ever. `git grep -nP '\x{2014}'` fails on git builds without
# Unicode \x{} PCRE; this perl form is portable:
perl -CSD -ne 'print "$ARGV:$.\n" if /\x{2014}/' $(git ls-files packages apps scripts)

A deterministic smoke-test failure is often a legitimate daemon behavior change rather than a regression. Read the trace's page snapshot (test-results/.../error-context.md) before assuming the wallet broke, then move the assertion to the new behavior. Do not skip the test.

Native SDK docs checkpoint (wavelength-mobile)

apps/docs/src/content/docs/native-ios-android/ condenses the wavelength-mobile repo. Find that checkout by a remote of lightninglabs/wavelength-mobile; older clones may carry the pre-rename lightninglabs/damobile URL, which GitHub redirects. Match the full path, not a prefix, or lightninglabs/wavelength will match and land you on the daemon.

These pages track wavelength-mobile's published state, not the daemon tag, so they never block a sync. After the main sync:

1. Run the mini-pass every time, even when sdk/wavewalletdk/mobile did not change: wavelength-mobile can rename types or rewrite its docs with no daemon release at all, so an unchanged facade is not evidence the pages are accurate. Each page opens with an MDX comment naming its upstream basis; diff its claims and snippets against that basis and confirm outbound links resolve. Three pages, and the quickstart's snippets are the only code.
2. If sdk/wavewalletdk/mobile changed in the range (git -C $WAVELENGTH_DIR diff --stat <pin>..<target> -- sdk/wavewalletdk/mobile) but wavelength-mobile has not adopted it yet, file a .tasks/ follow-up and finish the sync. The pages stay truthful meanwhile, since they describe the published wrapper and link out for volatile detail.

Common mistakes

• Guessed package filters: the docs app is @lightninglabs/wavelength-docs, the web package is @lightninglabs/wavelength-web, the demo is web-wallet-demo.
• Hand-editing apps/docs/src/data/api/wallet.json or packages/core/src/generated.ts. Both are generated and committed.
• Documenting CLI flags from --help or memory instead of cmd_*.go.

After the sync: improve this skill

Every release differs, so propose concrete edits to THIS file before finishing, and apply them on approval. The test for a candidate edit: would it help on a typical sync, or only on the exact change this release happened to carry? Durable environment facts and recurring change CLASSES belong here; a lesson tied to one field, file, or command quirk is a one-off that is easy to rediscover, so leave it out. Correct stale instructions rather than noting them, prune what the run proved obsolete, keep additions terse (name the file, the symptom, the fix), and propose the diff rather than committing it.