feat(templates): add raydium-hello-world community template

[cxalem]

What

New community template: raydium-hello-world — a Next.js + wallet-adapter + @raydium-io/raydium-sdk-v2 starter that swaps on a Raydium CPMM pool, devnet-first. Sibling to drift-hello-world in the protocol-intro series.

What it teaches:

• Raydium SDK init in a browser dApp: wallet PublicKey + signAllTransactions — no secret keys anywhere
• CPMM pool anatomy: reserves from RPC via cpmm.getPoolInfoFromRpc, price derived locally
• Per-keystroke local quoting with CurveCalculator (the on-chain constant-product math, zero RPC per keypress)
• Building, signing, and confirming a V0 swap transaction on devnet (incl. SOL wrapping)

Follows the kit-family design guidelines: Solana-branded grid background, neutral tokens, Inter + Geist Mono, next-themes dark mode, sonner toasts, shadcn primitives.

Deliberate decisions

• Devnet-pinned, no ClusterSelect — the default pool only exists on devnet; a cluster switcher would break the core flow. Pool is env-overridable (NEXT_PUBLIC_POOL_ID) and the in-app error state teaches recovery when a devnet pool dies (they do).
• .env.example committed via a !.env.example gitignore exception (placeholders only) — it documents the four optional env vars; the template runs with zero config.
• SDK pinned exact (0.2.60-alpha) — it's an alpha line; caret ranges would break fresh scaffolds on breaking alphas.
• Quote and amount travel as an atomic pair, and the quote object is cloned before cpmm.swap because the SDK applies the slippage discount by mutating the object passed in (retries would otherwise compound the discount).
• Generated catalog files intentionally not committed — they auto-commit on merge per generate-metadata.yml.

Review

Pre-push review ran through a dual-review agent pipeline (two independent reviewers + an external Codex pass auditing the decision log); all blocking findings fixed: quote/amount pairing, swapResult clone, .env.example shipping, README accuracy, full-signature copy affordance, wallet errors surfaced as toasts.

Test plan

• tsc --noEmit, template eslint, next build, repo lint (structure + prettier), pnpm generate + validate: all pass locally under pnpm 10.5.2
• Build-only swap transaction verified against the live devnet pool
• Draft until: end-to-end wallet swap re-verified on the final code + Raydium-branded og-image replaces the neutral placeholder; screenshots to be added then

[greptile-apps]

Greptile Summary

The PR adds a devnet-first Raydium CPMM swap template using Next.js, wallet-adapter, and Raydium SDK v2.

• Adds browser-side pool loading, local constant-product quoting, wallet signing, and transaction confirmation.
• Invalidates quotes by both input amount and pool-bundle identity.
• Clears pool state synchronously during refreshes and sequence-guards overlapping loads.
• Adds template configuration, documentation, styling, and dependency metadata.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
community/raydium-hello-world/src/hooks/use-swap.ts	Keys quote state to the exact amount and pool bundle, preventing the previously reported stale quotes from remaining visible or executable.
community/raydium-hello-world/src/hooks/use-pool.ts	Clears stale pool data at refresh start and prevents overlapping requests from committing out-of-order results.
community/raydium-hello-world/src/components/swap/swap-card.tsx	Enables execution only when a current quote and bundle exist and keeps the button disabled while a swap is active.
community/raydium-hello-world/src/lib/raydium.ts	Implements SDK initialization, local CPMM quoting, amount conversion, and transaction execution for the template.
community/raydium-hello-world/package.json	Defines the new template metadata, scripts, and pinned Raydium and wallet-adapter dependencies.

Sequence Diagram

sequenceDiagram
  participant U as User
  participant UI as Swap UI
  participant P as usePool
  participant S as useSwap
  participant R as Raydium/Solana
  P->>R: Load pool and reserves
  R-->>P: Pool bundle
  P-->>S: Current bundle
  U->>UI: Enter amount
  UI->>S: Current amount
  S->>S: Compute local quote
  S-->>UI: Quote keyed by amount and bundle
  U->>UI: Confirm swap
  UI->>S: Execute current quote
  S->>R: Build, sign, submit, confirm
  R-->>S: Transaction signature
  S->>P: Refresh pool
  P-->>UI: Clear bundle and disable Swap
  P->>R: Reload reserves

Loading

_{Reviews (5): Last reviewed commit: "fix(templates): invalidate pool data syn..." | Re-trigger Greptile}

[SrMessiSOL]

I reviewed the PR, including the existing Greptile threads and the latest fixes. The stale-quote issues look addressed, and I confirmed the branch merges cleanly into current main.

I would not approve yet only because the required checks are still failing (generate and Validate Template Metadata). Once those are rerun and green, this looks close to approval.

One small non-blocking wording suggestion: .env.example correctly says NEXT_PUBLIC_* values are browser-exposed, but the RPC example shows a Helius API-key URL. It may be safer to clarify that this should only be a public/throwaway devnet RPC endpoint, not a private or paid key.