Finally update the guestbook tutorial! - #2837
Open
ElliotFriend wants to merge 11 commits into
Open
Conversation
Stellar's smart-wallets docs still point at the retired passkey-kit + Launchtube stack. Launchtube's repo is archived and the hosted service is offline, so the existing guestbook tutorial can't be completed as written. Update the canonical references to the current stack: - passkey-kit → Smart Account Kit (https://github.com/kalepail/smart-account-kit) - OpenZeppelin Smart Account contracts (audited signer/policy framework) - Launchtube → OpenZeppelin Relayer (Stellar Channels plugin) Changes: - build/guides/contract-accounts/smart-wallets.mdx: rewrite the Tooling section. Lead with the current stack; flag passkey-kit + Launchtube as legacy with a pointer at the retirement. - build/guides/contract-accounts/advanced-patterns.mdx: add Smart Account Kit alongside the OZ + Crossmint reference implementations. - build/apps/guestbook/*: rewrite the 6-page tutorial against the new stack. The companion app is now a Cloudflare Pages deployment that uses Smart Account Kit + the OZ Channels relayer via a same-origin /api/relay proxy, so the API key stays server-side. The reference app lives at https://github.com/AshFrancis/ye-olde-guestbook (live: https://ye-olde-guestbook.pages.dev).
- throw `error(...)` instead of returning it in /api/relay, /api/fund, and /read/[id] snippets (SvelteKit's `error()` throws; `return` is misleading). - Add goto/resolve imports to signGuestbook snippet so readers copying it don't hit missing imports. - Overview: "fill in three things" → "two" (matches the .env snippet underneath, which has two vars). - Reword the relayer-key warning: we use Bearer auth, not URL-path auth, so the original phrasing was misleading.
Per Copilot feedback: the earlier snippet omitted PRIVATE_RELAYER_BASE_URL and only mentioned two variables to fill in, even though relayer.ts reads a third. Include it with its Testnet default so a reader who stays on the overview page has a complete picture of the relayer-related env vars.
kalepail/smart-account-kit and kalepail/passkey-kit are both archived and now live under the stellar org. Point every link at the new homes. The CLI has no `stellar keys show` subcommand; the one that prints a secret key is `stellar keys secret`.
Accuracy fixes that are independent of the smart-account stack, so they survive the rewrite: the contract uses `__constructor` (not `initialize`), `DataKey` is an enum, and the deploy command needs its constructor arguments after the `--` separator. Refs #1945 Co-Authored-By: Kaan Kacar <kaan.kacar@stellar.org> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Ash Francis's rewrite in #2367 targeted smart-account-kit 0.2.10 on Cloudflare Pages. ye-olde-guestbook now runs ^0.6.2 on Vercel, so point the pages at what the app actually does: /api/send rather than an /api/relay Pages Function, smartAccountClient.ts rather than passkeyClient.ts, the kit's autoFund and fundWallet rather than a funder G-account, and kit events rather than localStorage. Correct the indexer story while we're here. The kit defaults to Mercury's hosted smart-account-indexer, so the reverse lookup did not disappear with Launchtube, it just stopped being something you deploy yourself. Draw that boundary explicitly, since conflating the two breaks returning-user login on an unseen device. Refs #2367, #1945 Closes #2700 Co-Authored-By: Ash Francis <ash@ashfrancis.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
ye-olde-guestbook keeps its bindings in a pnpm workspace now, so `pnpm add file:./packages/ye_olde_guestbook` no longer reflects what the repo does. Use `pnpm add -D ye_olde_guestbook --workspace`, which records `workspace:*` the way the app's package.json does. Replace the nested `cd packages/... && pnpm install && pnpm run build` with the workspace housekeeping initialize.js actually performs: drop the standalone lockfile the CLI emits, and set a `prepare` script so pnpm compiles the bindings on install. Refs #2837 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The manual method now covers the pnpm workspace housekeeping, but the automated section's bullet list stopped at "generate bindings", so the two no longer described the same work. Name the prepare script, the dist/ gitignore, and the standalone lockfile removal, and correct the deploy bullet to mention the compile step. Refs #2837 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
preview
Contributor
The code blocks reproduced whole Svelte components, so only about 14% of their lines touched Smart Account Kit or the network. Two blocks (the sign-page form markup and the read/[id] component) had no Stellar content at all, and the form markup opened the tutorial's main event. Drop those two, trim the toast and loading-state ceremony from the rest, and mark every omission with a `// ...omitted:` comment naming what is gone. Lessons that the prose was narrating now live in code comments, so the signup section loses a paragraph that restated its own snippet. 311 code lines become 232 across 11 blocks rather than 13. Refs #2837 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The stack links were appended to the intro paragraph, which the llms plugin takes as the page description. That pushed it from 273 to 578 characters and tripped a build warning. Split the stack into its own paragraph. Refs #2837 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
preview
Contributor
ElliotFriend
marked this pull request as ready for review
September 9, 2026 19:34
This was referenced Sep 9, 2026
Closed
Contributor
There was a problem hiding this comment.
Pull request overview
This PR modernizes the smart-wallet documentation and the 6-page Guestbook tutorial to retire legacy Passkey Kit / Launchtube scaffolding and align the walkthrough with the current Smart Account Kit + OpenZeppelin Smart Account + OpenZeppelin Relayer (Stellar Channels) stack.
Changes:
- Updates the smart-wallets and advanced-patterns guides to recommend OpenZeppelin Smart Account, Smart Account Kit, and OpenZeppelin Relayer, while clearly labeling predecessor tooling.
- Rewrites Guestbook passkey setup/prereqs/frontend flows around Smart Account Kit (client config, event-driven session state, relayer proxy route, auto-funding, and simpler transfer/sign+submit patterns).
- Refreshes the Guestbook bindings and smart contract tutorial text to match the contract’s current constructor/init semantics and the workspace-based bindings workflow.
Recommendation: NEEDS-CHANGES — the relayer proxy route example needs small but important corrections (see PR comments on docs/build/apps/guestbook/setup-passkeys.mdx).
Reviewed changes
Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/build/guides/contract-accounts/smart-wallets.mdx | Replaces “tooling” section with the current recommended stack and relegates Passkey Kit/Launchtube to “predecessor tooling”. |
| docs/build/guides/contract-accounts/advanced-patterns.mdx | Adds direct pointers to OpenZeppelin Smart Account and Smart Account Kit as reference implementations. |
| docs/build/apps/guestbook/README.mdx | Clarifies the tutorial’s smart wallet/relayer stack at the section entry point. |
| docs/build/apps/guestbook/overview.mdx | Updates the tutorial overview and getting-started steps to match the new template/app assumptions and relayer usage. |
| docs/build/apps/guestbook/passkeys-prerequisites.mdx | Replaces Launchtube/Mercury setup with a single Relayer API key prerequisite and clarifies indexer responsibilities. |
| docs/build/apps/guestbook/setup-passkeys.mdx | Replaces Passkey Kit client/server setup with Smart Account Kit configuration, helpers, state tracking, and /api/send proxy route. |
| docs/build/apps/guestbook/frontend.mdx | Updates signup/login/logout, donation, write/edit flows to use Smart Account Kit patterns and relayer hash-based receipts. |
| docs/build/apps/guestbook/smart-contract.mdx | Updates smart contract narrative to reflect __constructor, DataKey enum, and other correctness/clarity fixes. |
| docs/build/apps/guestbook/bindings.mdx | Updates manual and automated bindings instructions for a pnpm-workspace workflow and constructor args in deploy. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Match the origin exactly rather than by substring, and explain why the forwarded payload is wrapped in `params` when the relayer guide's SDK examples aren't. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.
Suppressed comments (4)
Previously missed (2) — in code that hasn't changed since the last review.
docs/build/apps/guestbook/frontend.mdx:230
- This example throws a string (
throw '...'), which loses stack context and makes error handling inconsistent (many libraries and toasters expect anError). Prefer throwing anErrorinstance in examples.
This issue also appears in the following locations of the same file:
- line 268
- line 396
docs/build/guides/contract-accounts/smart-wallets.mdx:58
- The Passkey Kit repository link is inconsistent with other docs in this repo:
docs/build/guides/auth/check-auth-tutorials.mdx:617still points tohttps://github.com/kalepail/passkey-kit, while this page now points tohttps://github.com/stellar/passkey-kit. Please confirm the canonical repo/org and use the same URL across the docs to avoid sending readers to the wrong project.
docs/build/apps/guestbook/frontend.mdx:270
- This example throws a string (
throw "..."), which makes downstream error handling inconsistent. Preferthrow new Error(...)in examples.
if (!wallet.contractAddress) {
throw "user missing contract address";
}
docs/build/apps/guestbook/frontend.mdx:398
- This example throws a string (
throw "..."), which makes downstream error handling inconsistent. Preferthrow new Error(...)in examples.
if (!wallet.contractAddress) {
throw "user missing contract address";
}
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Retires the last of the passkey-kit, Launchtube, and Mercury/Zephyr setup from the guestbook tutorial, and brings it back in line with the app it documents.
Most of this is @AshFrancis's work from #2367, cherry-picked so his authorship stays in the history rather than being paraphrased. He did the hard part: restructuring all six pages around Smart Account Kit, the OpenZeppelin Smart Account, and the OpenZeppelin Relayer. Three of the six commits here are his. Also carried over a couple of @kaankacar's commits, plus the accuracy fixes from my own stale #1945 (
__constructorrather thaninitialize,DataKeyis anenum, constructor args in the deploy command).Ash wrote against smart-account-kit
0.2.10on Cloudflare Pages, and ye-olde-guestbook has since moved to^0.6.2on Vercel, so I re-aimed the mechanics:/api/sendrather than an/api/relayPages Function,smartAccountClient.tsrather thanpasskeyClient.ts, the kit'sautoFundandfundWallet()rather than a funder G-account, kit events rather than localStorage, and a one-lineaccount.transfer()rather than hand-builtScValargs.setup-passkeys.mdxcomes out about 300 lines shorter as a result.One correction to his version: it said there was "no passkey to contract reverse-lookup indexer to set up," which reads as though indexing went away with Launchtube. It did not. The kit still defaults to Mercury's hosted
smart-account-indexer; there is just nothing left for the dev to deploy. That page now says plainly that OpenZeppelin replaced Launchtube's submission and fee-sponsorship role, not Mercury's indexing role, which is the confusion @kalepail flagged in #2700.Please do not merge yet
overview.mdxdescribesstellar-template-sveltekit-passkeys(https://github.com/ElliotFriend/stellar-template-sveltekit-passkeys) as it will be. That repo still shipspasskey-kit ^0.11.1, Launchtube, Mercury, and a funder secret, so a reader who clones it today gets none of the code these pages describe. I am updating it separately; this stays in draft until that lands.pnpm build,check:mdx, and the link checker all pass. Every SDK claim was checked against the installed 0.6.2 types and the contract source rather than from memory.Supersedes #1945 and #2367, both of which can close once this lands.
Closes #2700
🤖 Generated with Claude Code (https://claude.com/claude-code)