docs: modernize smart-wallets references + rewrite guestbook tutorial - #2367
docs: modernize smart-wallets references + rewrite guestbook tutorial#2367AshFrancis wants to merge 7 commits into
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).
There was a problem hiding this comment.
Pull request overview
Modernizes Stellar smart-wallet documentation and rewrites the Guestbook tutorial so it can be completed end-to-end using the current smart-account stack (Smart Account Kit + OpenZeppelin Smart Account + OpenZeppelin Relayer/Channels), replacing legacy Passkey Kit/Launchtube/Mercury dependencies.
Changes:
- Updates canonical smart-wallet reference pages to point to OpenZeppelin Smart Account, Smart Account Kit, and OpenZeppelin Relayer (Channels).
- Rewrites the Guestbook tutorial to use a server-side
/api/relayproxy + funder account flow instead of Launchtube/Mercury. - Refreshes tutorial snippets and setup steps (bindings, prerequisites, overview) to match the new stack and deployment model.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/build/guides/contract-accounts/smart-wallets.mdx | Replaces outdated tooling refs with current smart-account building blocks + notes predecessor tools. |
| docs/build/guides/contract-accounts/advanced-patterns.mdx | Adds Smart Account / Smart Account Kit references to advanced patterns resources. |
| docs/build/apps/guestbook/setup-passkeys.mdx | Rewrites passkey setup around Smart Account Kit + OZ Relayer proxy and new fund endpoint approach. |
| docs/build/apps/guestbook/passkeys-prerequisites.mdx | Updates prerequisites from Launchtube/Mercury to OZ Relayer API key + funder account. |
| docs/build/apps/guestbook/overview.mdx | Updates tutorial overview, repo links, deployment notes, and environment setup guidance. |
| docs/build/apps/guestbook/frontend.mdx | Updates frontend walkthrough to use Smart Account Kit flows and updated transaction patterns. |
| docs/build/apps/guestbook/bindings.mdx | Updates bindings-client snippet and references to the new guestbook repo + initialize script. |
| docs/build/apps/guestbook/README.mdx | Refreshes summary to name the new recommended stack and link to relevant docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- 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.
smart-contract.mdx still linked to ElliotFriend/ye-olde-guestbook for lib.rs/types.rs/test.rs, while every other guestbook page links to AshFrancis/ye-olde-guestbook. Files are byte-identical in both repos, but keeping the reader on one repo avoids confusion when they've cloned the fork and are following along.
|
This PR still appears to resolve both live smart-wallet/Guestbook defects: main routes readers to legacy Passkey Kit and requires a LaunchTube JWT, while current guidance says LaunchTube is discontinued and Passkey Kit directs new apps to Smart Account Kit. CI is green; could a maintainer review/merge it or identify the remaining blocker? |
|
Following up on my 2026-07-14 note: this PR now shows merge conflicts against Both defects it fixes are still live on
@AshFrancis — is this still something you want to carry? No pressure either way. So the defects stay tracked independently of the branch, I've opened #2700; happy to close that the moment this lands. |
Resolved the four content conflicts on the guestbook and smart-wallet pages. Kept this branch's rewrite and took main's title capitalization, its nested-anchor fix in the overview intro, and its trailing-slash cleanups on external links.
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`.
|
🤖 Automated message from Kaan's Automated Triage Bot. Reviewing because a review was requested by @ElliotFriend. Decision needed: should this tutorial point at Pushed to the branch: a merge of |
kaankacar
added
the
bot:needs-decision
|
Should stay on ElliotFriend/ye-olde-guestbook as this has now been updated in ElliotFriend/ye-olde-guestbook@6b78e46 tutorial may need some updates to reflect @ElliotFriend 's approach here. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.
Suppressed comments (2)
docs/build/apps/guestbook/setup-passkeys.mdx:110
- Current Smart Account Kit submission methods return a
TransactionFailurefor expected relayer or on-chain failures instead of throwing. Since all tutorial callers simply awaitsend(), they proceed to redirects/success toasts after a failed submission. Convert unsuccessful results into an exception here so the existing callercatchblocks work.
export async function send<T>(tx: AssembledTransaction<T>) {
const kit = await loadKit();
return kit.signAndSubmit(tx);
}
docs/build/apps/guestbook/frontend.mdx:155
localStorage.clear()deletes every key owned by this origin, not just the guestbook session. Logging out should not erase unrelated preferences or state; remove only the twoyog:*entries this store owns.
window.localStorage.clear();
| :::warning Production checklist | ||
|
|
||
| The implementation of this is outside the scope of this tutorial, but be sure to consider these kinds of risks as you prepare for a more production-level deployment. | ||
| For production, add rate limiting and origin checking to this endpoint so a bad actor can't burn your relayer credits forwarding arbitrary transactions. Out of scope for this tutorial, but don't skip it before going to Mainnet. |
There was a problem hiding this comment.
🤖 Automated message from Kaan's Automated Triage Bot.
Reviewing because a review was requested by @ElliotFriend.
Not applying this one. The page already tells the reader to add rate limiting and origin checking before Mainnet. Contract allowlisting and fee ceilings go past the scope of a Testnet tutorial that says not to deploy it to Mainnet. The companion app keeps the same origin check.
| publicKey: fundKeypair.publicKey(), | ||
| signAuthEntry: (auth) => fundSigner.signAuthEntry(auth), | ||
| }); | ||
| export const GET: RequestHandler = async ({ params }) => { |
| reset = () => { | ||
| this.keyId = null; | ||
| this.contractAddress = null; | ||
| window.localStorage.clear(); | ||
| window.location.reload(); |
|
|
||
| What more could you want!? | ||
| - a starter `/contracts` directory containing the guestbook Rust contract, | ||
| - a pre-configured `package.json` with Smart Account Kit, the OpenZeppelin Relayer client, and SvelteKit's Cloudflare adapter, |
| * A Stellar RPC server instance. Safe to import from server routes — this is | ||
| * the stock stellar-sdk RPC client, with no browser dependencies. | ||
| */ | ||
| export const rpc = new Server(PUBLIC_STELLAR_RPC_URL); |
| // G-address stand-in for the source — stellar-sdk's Account rejects | ||
| // C-addresses. signAndSubmit re-signs with its own deployer before | ||
| // submitting, so this only affects the initial simulation. |
|
|
||
| We're setting this up in `src/lib/server/passkeyServer.ts`, for similar reasons we listed above. This gives us an importable `server` instance that can be accessed and used in other server-side logic. Svelte gives us the added benefit of [keeping the code in this directory safe](https://svelte.dev/docs/kit/server-only-modules#Your-modules). When we want to safeguard credentials and secrets, we can put any sensitive code in the `$lib/server` directory. | ||
| - **`{ func, auth }`** (Soroban host function + auth entries) → forwarded to OZ Channels, which wraps it in a channel-account transaction and pays fees. This is the sponsored path that user actions take (`kit.signAndSubmit`). | ||
| - **`{ xdr }`** (fully-signed envelope) → sent straight to Stellar RPC. Smart Account Kit's wallet-deploy flow takes this path: it signs with its shared deployer keypair (well-known, pre-funded on Testnet). OZ Channels rejects signed envelopes where `tx.fee != tx.sorobanData.resourceFee` — stellar-sdk's default fee includes a safety margin that breaks that strict equality — so we bypass the relayer for this specific case. |
|
🤖 Automated message from Kaan's Automated Triage Bot. Reviewing because a review was requested by @ElliotFriend. @AshFrancis confirmed the tutorial should follow
Decision needed: re-aim the 6-page tutorial at Elliot's current app, or land the two smart-wallet reference pages alone and rewrite the tutorial separately? @kaankacar @ElliotFriend I pushed no fix this time. Repointing the links alone would send readers to a repo that has none of these files. Copilot's other six findings are correct and all trace to the |
|
superseded by #2837 |
|
PR Preview: torn down |
Stellar's smart-wallets docs still point at passkey-kit and Launchtube. Launchtube's repository is archived and the hosted service at launchtube.xyz is offline, so the existing guestbook tutorial can't be completed end-to-end.
Updates the canonical smart-wallets references (
smart-wallets.mdx,advanced-patterns.mdx) to point at the current stack: Smart Account Kit, OpenZeppelin Smart Account, and the OpenZeppelin Relayer (Stellar Channels).Rewrites the 6-page guestbook tutorial (
docs/build/apps/guestbook/*) against that stack. Drops the Mercury/Zephyr reverse-lookup indexer (Smart Account Kit keeps credential metadata in IndexedDB) and the Launchtube prerequisite (replaced by an OZ Channels API key). Switches the deploy target from Vercel to Cloudflare Pages so the/api/relayproxy can live alongside the static app.Companion app updated: https://github.com/AshFrancis/ye-olde-guestbook (live on Testnet: https://ye-olde-guestbook.pages.dev).